selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

docker-pi-hole logo

Self-host docker-pi-hole

2026.11.0

DNS-based network ad blocking in an official Docker image

ReleaseOpen SourceOther
Docker ComposeCompose file & guide
docker compose up -d
Updated4 days ago
LanguageShell
Setup difficultyEasy
Stars
11 780
Rating
5.0 (1)
RAM
512MB
Storage
Min. 2GB free space, 4GB recommended
Ports
53 (DNS (TCP and UDP)), 80 (Web interface over HTTP), 443 (Web interface over HTTPS with an FTL-generated self-signed certificate), 67 (DHCP server, optional)
Docker
pihole/pihole

What is docker-pi-hole?

Docker Pi-hole is the official container image of Pi-hole, the DNS sinkhole that filters advertising and tracking lookups for every device behind your router. Because blocking happens at the network layer, it reaches phones, TVs and IoT gear where no browser add-on can be installed. The image packs Pi-hole Core, the web interface and the pihole-FTL resolver together, so no separate web server is needed: you get dashboard statistics, a searchable query log, per-client groups, regex filtering, subscribed blocklists and allowlists that the container's baked-in cron refreshes weekly, four privacy modes, an optional DHCP server and a REST API with built-in documentation. Deploy the pihole/pihole image in a compose file that exposes 53, 80 and 443 (add 67 and 123 for DHCP or NTP), set a timezone and a web-interface password, and mount ./etc-pihole at /etc/pihole so your data survives image updates. Further FTL settings arrive as FTLCONF_ environment variables, which override pihole.toml and then become read-only in the UI. Numbering is date-based, such as 2026.09.0, rather than semantic, and the nightly tag is experimental. The docs advise against running the container with --privileged and instead adding only the capabilities you need.

docker-pi-hole alternatives

Should you self-host docker-pi-hole?

docker-pi-hole scores 77/100 on selfhost.directory (how scoring works) and ranks #3 of 41 in DNS. It has 11 780 GitHub stars, +113 in the last 30 days.

It shipped 13 stable releases in the past year. The latest, 2026.11.0, came out on 11 November 2026. New versions land roughly every 3 weeks.

Setup is easy: most people get it running in one sitting. An official Docker image is available. It is Other-licensed and written mostly in Shell.

Its closest alternative on selfhost.directory is Pi-hole (88/100, 62 035 stars). It scores higher overall, so compare the two before you pick. See docker-pi-hole vs Pi-hole side by side.

Features

  • Backup & Restore
  • Blocklist & allowlist subscriptionscron inside the container updates lists once per week
  • Built-in DHCP serverrequires port 67 and the NET_ADMIN capability
  • Client group management
  • DNS-based ad blocking
  • DNS Caching
  • Host networking mode
  • HTTPS web interface
  • NTP Serveroptional
  • Privacy Modes
  • Query Log
  • Regex domain filtering
  • REST API
  • Scheduled list updates
  • Web Dashboard

docker-pi-hole README

How to install docker-pi-hole

Install docker-pi-hole with Docker

docker run --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 443:443/tcp -e TZ=Europe/London -e FTLCONF_webserver_api_password="correct horse battery staple" -e FTLCONF_dns_listeningMode=all -v ./etc-pihole:/etc/pihole -v ./etc-dnsmasq.d:/etc/dnsmasq.d --cap-add NET_ADMIN --restart unless-stopped pihole/pihole:latest

How to configure docker-pi-hole

  • TZTimezone so logs rotate at local midnight instead of UTC midnight.
  • FTLCONF_webserver_api_passwordPassword for the web interface; a random one is assigned and printed to the container log if unset.
  • FTLCONF_dns_listeningModeDNS listening mode; set to 'ALL' when using Docker's default bridge network.

    values: ALL

  • FTLCONF_dns_upstreamsUpstream DNS servers Pi-hole forwards queries to, semicolon-separated; supports #port suffixes and Docker service names.
  • FTLCONF_dns_dnssecEnable DNSSEC validation; mirrors the dnssec setting in pihole.toml.

    values: true|false

docker-pi-hole releases & version history

@ Every self-hosted release, weekly

One Monday email with the week's stable releases across the directory.

FAQ

In which order are locally defined DNS records used?

The device's hostname and pi.hole first, then configs in /etc/dnsmasq.d/, then /etc/hosts, and finally the local custom DNS list in /etc/pihole/custom.list; only the first match is used for address-to-name association.

Why does Pi-hole's gravity complain about invalid IDN domains?

Blocklists contain Internationalized Domain Names that DNS servers never see; ask the list maintainer to convert them to their Punycode representation.

Why does the Pi-hole update fail with a message that the repository changed its 'Suite' value?

This appears after manually upgrading a Debian-based OS to the next major version; run apt-get update with the --allow-releaseinfo-change flag.

Why do I see odd random character queries in Pi-hole's query logs?

Chrome-based browsers send randomly generated 7-15 character domain names to detect wildcard DNS tampering, so those strings show up as queries in the log.

More in DNS

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…