Self-host docker-pi-hole
2026.11.0DNS-based network ad blocking in an official Docker image
docker compose up -d- 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)
pihole/piholeWhat 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
ph-interceptph-intercept is a self-hosted, open-source DNS dashboard that visualizes live query traffic from Pi-hole v6, AdGuard Home, or Technitium as an arcade-style space shooter.Compareph-intercept with docker-pi-hole
gatekeeperSelf-hosted DHCP/DNS server for home networks with web dashboard, Full Cone NAT, and zero-config setup.Comparegatekeeper with docker-pi-hole
pia-wireguardSelf-hosted WireGuard VPN client container that routes Docker workloads through a PIA tunnel, with port forwarding, a default-deny kill-switch firewall and healthchecks.Comparepia-wireguard with docker-pi-hole
GoAwayGoAway is a self-hosted, open-source DNS sinkhole written in Go that blocks ads, trackers, and malicious domains at the network level with a web-based admin dashboard.CompareGoAway with docker-pi-hole
Technitium DNS ServerSelf-hosted, open-source authoritative and recursive DNS server with a web console, DNS sinkhole ad blocking, DoH/DoT/DoQ, and a built-in DHCP server.CompareTechnitium DNS Server with docker-pi-hole
RaspAPOpen-source, self-hosted wireless router and access point web interface for Debian-based devices like the Raspberry Pi, adding VPN, ad blocking and DHCP control.CompareRaspAP with docker-pi-hole
nebula-syncSelf-hosted, open-source tool to sync config across multiple Pi-hole v6.x instances using full Teleporter or selective feature sync with cron scheduling.Comparenebula-sync with docker-pi-hole
docker-ddnsSelf-hosted dynamic DNS server using Docker, Go, and Bind9 that lets you connect to home devices from anywhere using a VPS and domain.Comparedocker-ddns with docker-pi-hole
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
Note
Using Watchtower?
See the Note on Watchtower in our documentation.
Tip
Some users have reported issues with using the --privileged flag on 2022.04 and above.
TL;DR, don't use that mode, and be explicit with the permitted caps (if needed) instead.
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
docker-traefik-cloudflare-companionSelf-hosted Docker companion that automatically creates and updates Cloudflare CNAME records for containers managed by Traefik reverse proxy.
DockFlareOpen-source, self-hosted control plane turning Docker labels into Cloudflare Tunnel routes, DNS entries and Zero Trust policies, with an optional sovereign email suite.
DomainMODDomainMOD is an open source application written in PHP & MySQL used to manage your domains and other internet assets in a central location. DomainMOD also includes a Data Warehouse framework that allows you to import your web server data so that you can view, export, and report on your live data.
dynagodynago is a self-hosted, open-source dynamic DNS updater in Go that monitors your public IP and updates Cloudflare or Route 53 records when it changes.
gatekeeperSelf-hosted DHCP/DNS server for home networks with web dashboard, Full Cone NAT, and zero-config setup.
GoAwayGoAway is a self-hosted, open-source DNS sinkhole written in Go that blocks ads, trackers, and malicious domains at the network level with a web-based admin dashboard.
GravitySelf-hosted DNS, DHCP, TFTP server using etcd for cluster replication. Includes ad-blocking, auto DNS registration for DHCP, Wake-on-LAN, Prometheus metrics.
guardium-dnsSelf-hosted parental control dashboard for Technitium DNS with profiles, schedules, quotas, and optional ASUS router integration. Free, open-source.
hestiaOpen-source, self-hosted control panel for Debian and Ubuntu servers: manage web domains, mail, DNS zones, databases and free SSL from one dashboard.
LuckySelf-hosted networking suite for routers: IPv6/IPv4 port forwarding, DDNS, reverse proxy, STUN tunneling, WOL, ACME certs, run as one Go binary with a web admin UI.
Maza ad blockingOpen-source, self-hosted local ad blocker written only in Bash: one command rebuilds your hosts file to block ad domains, no browser extensions needed.
mikrotik-dnsSelf-hosted DNS analytics dashboard collecting MikroTik logs via UDP with real-time React UI, domain/client analysis, and live DNS search.
0 comments