Pi-hole with Docker: Block Ads and Trackers for Your Whole Network (Linux, Windows, Mac)
Before you start
- 21 min read
Boxes marked Run in terminal are what you type; plain text explains why. Check what you need first

What you get in one minute#
Pi-hole is a free DNS server that blocks ads, trackers and known-bad domains for every device on your network at once: your devices ask Pi-hole for a name first, and Pi-hole simply refuses to answer for the blocked ones.
Logo: the official Pi-hole project (pi-hole.net). The name and logo are Pi-hole trademarks, shown here only to identify the tool.
Nothing is installed on your phones, TVs or laptops. You run one small container on an always-on machine, tell your router to hand out its address as the DNS server, and watch blocked queries pile up in a dashboard. It blocks by name only: an ad served from the same domain as the content you want cannot be separated.
| What | Value (official sources, read 16 November 2026) |
|---|---|
| Image to pin | pihole/pihole:2026.11.0, a Docker release of 11 November 2026 (Core v6.6, Web v6.6.1, FTL v6.9). The previous one is 2026.10.1, from 31 October 2026 |
| Time needed | About 20 minutes (our estimate, not measured) |
| Size and RAM | The docs ask for 512 MB RAM and 2 GB free disk (4 GB recommended). Docker Hub lists the tag at about 42 MB compressed |
| Ports | 53 TCP and UDP (DNS), 80 and 443 TCP (web page); optional 67 UDP (DHCP) and 123 UDP (NTP) |
| Platforms | The Docker Hub tag lists amd64, arm64, 386, arm v7, arm v6 and riscv64 |
| Licence | EUPL-1.2 (the LICENSE file at the release tag). Name and logo are trademarks |
| Official docs | docs.pi-hole.net and github.com/pi-hole/docker-pi-hole |
At a glance:
- What it is: a DNS server with blocklists and a web dashboard, in one container.
- v6 is a different program inside: the web server changed and most environment variables were renamed. Old guides mislead; see what changed.
- Port 53 is the usual blocker: on Ubuntu,
systemd-resolvedholds it (Step 1). - Run it on Linux: Docker Desktop on Windows or Mac is for testing only.
- Pin the tag: the docs warn against unattended updates.
- Privacy: allowed lookups go on to the upstream resolver you choose.
How it fits together#
Devices ask Pi-hole on port 53. It answers blocked names with an empty address and forwards the rest to your upstream DNS. The admin page is a separate web port.
Drawn for this guide from the official Docker README and docs. DNS never goes through the HTTPS proxy; only the admin page does.
Before you start#
Run Pi-hole on a small always-on Linux machine (a Raspberry Pi, a mini PC, a home server). Pi-hole's own README calls it "network-wide ad blocking via your own Linux hardware". If Pi-hole is off, every device on your network loses the internet.
Docker Desktop on Windows or Mac works for trying it out. We would not run your home on it: the official docs describe neither platform, a laptop sleeps and moves networks, and Docker Desktop's host networking is only host-to-container access, so we do not expect DHCP (below) to work. In our AdGuard Home guide we noted that behind Docker Desktop all devices can look like one address.
| Need | Value |
|---|---|
| RAM and disk | 512 MB RAM; 2 GB free disk minimum, 4 GB recommended (prerequisites page) |
| Linux hosts the docs support | Alpine, Armbian, Debian, CentOS Stream, Fedora, Raspberry Pi OS, Ubuntu (actively maintained versions) |
| IP address | A fixed address: a DHCP reservation on your router is fine |
| Ports free | 53 TCP/UDP and 80/443 TCP on the host (change 80/443 later if needed) |
| For HTTPS only | A name for the page (a domain, or a home name with tls internal) |
Linux#
docker --version docker compose version
Windows (PowerShell)#
docker --version docker compose version
Mac (Terminal)#
Same commands as Linux:
docker --version docker compose version
Checklist:
- [ ] Docker and the Compose plugin on the machine that will run Pi-hole
- [ ] Its address is fixed (DHCP reservation) and you know it: this guide writes it as
<server-ip> - [ ] You can sign in to your router's admin page
- [ ] You can undo the DNS change (write down your router's current DNS setting first)
Tested on: not run by us. Every command comes from the official docs and release files read on 16 November 2026.
Step 1: Free port 53#
Only one program can listen on port 53. Ubuntu and Fedora ship systemd-resolved, whose stub listener takes it, so Docker fails with "address already in use".
Linux#
Look first:
sudo ss -lntup | grep ':53 '
If systemd-resolve owns it, use the official method (Pi-hole docs, "Tips and Tricks"):
sudo sh -c 'mkdir -p /etc/systemd/resolved.conf.d && printf "[Resolve]\nDNSStubListener=no\n" | tee /etc/systemd/resolved.conf.d/no-stub.conf' sudo sh -c 'rm -f /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf' sudo systemctl restart systemd-resolved
The first command switches the stub off; the second points /etc/resolv.conf at the real DNS servers.
Windows (PowerShell)#
Docker Desktop publishes the port on Windows. Check that nothing else holds it:
netstat -ano | findstr ":53 "
Mac (Terminal)#
sudo lsof -nP -iUDP:53 -iTCP:53 -sTCP:LISTEN
Check it worked. Nothing is listed (on Linux, ss prints nothing). If a program is, stop it or choose another machine.
Tip: Do not point this machine's own DNS at Pi-hole yet. If Pi-hole is the host's only DNS and it is down, the host cannot pull the image to repair it (docs).
Step 2: Create the folder and the password file#
The password goes into a .env file next to the Compose file, not into the YAML.
Linux#
mkdir -p ~/docker_volumes/pihole/{data,backups}
cd ~/docker_volumes/pihole
printf 'TZ=Europe/London\nFTLCONF_webserver_api_password=%s\n' "$(openssl rand -base64 24)" > .env
chmod 600 .env
Replace Europe/London with your time zone. Read the password once with cat .env and save it in a password manager.
Windows (PowerShell)#
New-Item -ItemType Directory -Force "$HOME\docker_volumes\pihole\data", "$HOME\docker_volumes\pihole\backups" | Out-Null
Set-Location "$HOME\docker_volumes\pihole"
$b = New-Object byte[] 24
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
Set-Content -Path .env -Encoding ascii -Value "TZ=Europe/London", ("FTLCONF_webserver_api_password=" + [Convert]::ToBase64String($b))
Mac (Terminal)#
Same commands as Linux.
Check it worked. .env has two lines (grep -c . .env, or (Get-Content .env).Count on Windows) and the password is not empty.
Tip: Never leave
FTLCONF_webserver_api_passwordempty. In Pi-hole v6 an empty value ('') means "no password at all", which is different from not setting it. In one issue thread the maintainers explained that unset gives a random password, empty gives none.
Step 3: Write the Compose file and start Pi-hole#
This is the official quick-start with four changes: the image is pinned, the password and time zone come from .env, the data lives in ./data, and the optional capabilities are left out. The docs require FTLCONF_dns_listeningMode: ALL for Docker's bridge network. The :? stops Compose if the password is missing.
Linux#
cd ~/docker_volumes/pihole
cat > compose.yaml << 'EOF'
services:
pihole:
image: pihole/pihole:2026.11.0
container_name: pihole
restart: unless-stopped
ports:
- "53:53/tcp"
- "53:53/udp"
- "80:80/tcp"
- "443:443/tcp"
environment:
TZ: ${TZ:-Etc/UTC}
FTLCONF_webserver_api_password: ${FTLCONF_webserver_api_password:?Set the password in .env}
FTLCONF_dns_listeningMode: ALL
volumes:
- ./data:/etc/pihole
EOF
docker compose up -d
docker compose ps
docker logs pihole --tail 30
On Red Hat based systems with SELinux enforcing, write the volume as ./data:/etc/pihole:z (docs). If something else already uses port 80, change that line to "8080:80/tcp" (docs).
Windows (PowerShell)#
Set-Location "$HOME\docker_volumes\pihole"
@'
services:
pihole:
image: pihole/pihole:2026.11.0
container_name: pihole
restart: unless-stopped
ports:
- "53:53/tcp"
- "53:53/udp"
- "80:80/tcp"
- "443:443/tcp"
environment:
TZ: ${TZ:-Etc/UTC}
FTLCONF_webserver_api_password: ${FTLCONF_webserver_api_password:?Set the password in .env}
FTLCONF_dns_listeningMode: ALL
volumes:
- ./data:/etc/pihole
'@ | Set-Content -Path compose.yaml -Encoding ascii
docker compose up -d
docker compose ps
docker logs pihole --tail 30
Mac (Terminal)#
Same commands as Linux.
Check it worked. docker compose ps shows pihole running and the log ends without errors. The docs publish no expected log text; a public issue report from an older tag shows [i] Starting FTL configuration and [i] Assigning password defined by Environment Variable, so yours may differ.
Tip: Use
docker compose downanddocker compose up -dto apply changes. Environment variables are read at start.
Step 4: Log in, choose an upstream and test#
Linux#
Open http://<server-ip>/admin and sign in with the password from .env. Port 443 serves a self-signed certificate, so a browser warning there is expected.
In Settings, DNS pick an upstream DNS server. The docs list Quad9 (9.9.9.9, 149.112.112.112) and Cloudflare (1.1.1.1, 1.0.0.1) among the presets. With none set, Pi-hole cannot resolve outside names (docs).
Test from another computer on your network. This needs dig (Debian and Ubuntu: sudo apt install dnsutils):
dig @<server-ip> example.com +short dig @<server-ip> example.com +short +tcp docker exec pihole pihole deny advertiser.example.com dig @<server-ip> advertiser.example.com +short
Windows (PowerShell)#
Resolve-DnsName example.com -Server <server-ip> Resolve-DnsName example.com -Server <server-ip> -TcpOnly docker exec pihole pihole deny advertiser.example.com Resolve-DnsName advertiser.example.com -Server <server-ip>
Mac (Terminal)#
Same commands as Linux (dig ships with macOS).
Check it worked. The first two lookups return an address. The last returns 0.0.0.0: in the default mode blocked queries get the "unspecified address" (docs). The Query Log shows them. Remove the test entry later under Domains.
Tip: Test from a second device, not only from the Docker host. A container that answers on
localhostcan still be unreachable from the network.
Step 5: Point your network at Pi-hole#
The goal is that every device gets <server-ip> as its DNS server. Three ways, best first.
- Router (best). In your router's DHCP settings set the DNS server to
<server-ip>, then renew the leases (reconnect Wi-Fi). The Pi-hole docs have pages for several routers. Leave the second DNS entry empty: a public one lets devices skip Pi-hole. - Pi-hole as the DHCP server. See the next section. Disable your router's DHCP first.
- Per device (last resort).
Linux#
With NetworkManager (replace the connection name):
nmcli connection modify "<connection>" ipv4.dns <server-ip> ipv4.ignore-auto-dns yes nmcli connection up "<connection>"
Windows (PowerShell, as administrator)#
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ServerAddresses <server-ip> # undo: Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses
Mac (Terminal)#
sudo networksetup -setdnsservers "Wi-Fi" <server-ip> # undo: sudo networksetup -setdnsservers "Wi-Fi" empty
Check it worked. Browse on a device: its address appears in the Query Log. The docs suggest http://pi.hole/admin/ as a test; it works only when the device really uses Pi-hole.
Tip: If ads still show on one device, open its network settings and look for a second DNS server, or for "secure DNS" in the browser, which skips Pi-hole.
Optional: Pi-hole as your DHCP server#
DHCP works by broadcast, and a broadcast cannot cross Docker's bridge. The docs name three ways: host networking (simplest), a macvlan network (own LAN address, harder), or a bridge plus a DHCP relay.
For host networking, remove the ports: block in compose.yaml, add these lines and recreate the container:
network_mode: host
cap_add:
- NET_ADMIN
Then turn on DHCP in the web interface and switch your router's DHCP off: only one DHCP server may run. The container now shares the host's ports; move web ports with FTLCONF_webserver_port (docs). We did not test this variant. Linux only.
Put it behind HTTPS (with or without Traefik)#
This is for the admin page only; DNS never goes through a proxy. Pi-hole already serves HTTPS on port 443 with a self-signed certificate, so at home you can skip this. Both routes need a password (Step 2): since v6.8, with no password Pi-hole only answers browser requests that use a name it knows (IP addresses, pi.hole, the hostname), so a proxy name gets 403 Forbidden (maintainers, FTL issue 3268).
For either route, change compose.yaml: delete the "80:80/tcp" and "443:443/tcp" lines (the proxy reaches the web page inside the Docker network on port 80) and join the shared proxy network. Create it once:
docker network create proxy
With Traefik#
On a server that already runs Traefik v3 with the Docker provider and an entrypoint named https:
services:
pihole:
image: pihole/pihole:2026.11.0
container_name: pihole
restart: unless-stopped
ports:
- "53:53/tcp"
- "53:53/udp"
environment:
TZ: ${TZ:-Etc/UTC}
FTLCONF_webserver_api_password: ${FTLCONF_webserver_api_password:?Set the password in .env}
FTLCONF_dns_listeningMode: ALL
volumes:
- ./data:/etc/pihole
networks:
- default
- proxy
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.pihole.rule=Host(`pihole.<your-domain>`)"
- "traefik.http.routers.pihole.entrypoints=https"
- "traefik.http.routers.pihole.tls=true"
- "traefik.http.services.pihole.loadbalancer.server.port=80"
networks:
proxy:
external: true
Run docker compose up -d. Check it worked. curl -I https://pihole.<your-domain>/admin/ returns an HTTP status over HTTPS, and the page opens with a valid certificate. A sub-path such as /pihole needs webserver.paths.prefix and a strip-prefix middleware (config reference); use a hostname instead.
Without Traefik: Caddy#
Caddy gets and renews certificates itself: Let's Encrypt for a public domain, or tls internal (its own local certificate) at home.
Use the Pi-hole file above without the labels: block. Caddy gets the whole conf folder, not one file, because Caddy's Docker docs warn that editors can break a single-file mount:
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
cd ~/docker_volumes/caddy
~/docker_volumes/caddy/compose.yaml (caddy:2.11.9 was the newest release on 16 November 2026):
services:
caddy:
image: caddy:2.11.9
container_name: caddy
restart: unless-stopped
ports:
- "80:80/tcp"
- "443:443/tcp"
- "443:443/udp"
volumes:
- ./conf:/etc/caddy:ro
- ./data:/data
- ./config:/config
networks:
- proxy
networks:
proxy:
external: true
~/docker_volumes/caddy/conf/Caddyfile for a public domain:
pihole.example.com {
reverse_proxy pihole:80
}
For a home-only name (point it at the Caddy machine in Pi-hole's own local DNS records):
pihole.home.arpa {
tls internal
reverse_proxy pihole:80
}
Start both stacks, Caddy last:
cd ~/docker_volumes/pihole && docker compose up -d cd ~/docker_volumes/caddy && docker compose up -d
With tls internal, each device must trust Caddy's root certificate. Copy it out and install it (the second Linux line is for other Linux devices):
docker exec caddy find /data -name root.crt docker cp caddy:<path-from-find> ./caddy-root.crt sudo cp caddy-root.crt /usr/local/share/ca-certificates/caddy-root.crt && sudo update-ca-certificates
On Windows (PowerShell as administrator): certutil -addstore -f ROOT caddy-root.crt. On Mac: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain caddy-root.crt.
Check it worked. curl -I https://pihole.example.com/admin/ returns a status line over HTTPS. For a home-only name the padlock appears only after the root is trusted.
Tip: Let's Encrypt needs the DNS record to point at the server and ports 80 and 443 to reach it. For a home-only name use
tls internaland never forward those ports. See our Caddy guide.
Security and testing#
| Control | How |
|---|---|
| Never expose DNS to the internet | listeningMode: ALL answers everyone who can reach the port. The docs warn this can make Pi-hole an open resolver. Do not forward port 53 on your router |
| Docker bypasses ufw | Published ports skip ufw's rules (Docker docs). Keep the host off the public internet, or bind the DNS lines to <server-ip> |
| Admin password | Long, unique, in .env (chmod 600). Pi-hole supports 2FA (TOTP), and scripts can use an application password |
No --privileged, no Docker socket | The official example needs neither. Add NET_ADMIN only for DHCP and SYS_TIME only for NTP |
| Debug output | pihole -d uploads once included password hashes and the TOTP secret; Core v6.6 fixed that. Never post a debug log unread |
Backups and .env | They hold secrets and history: chmod 600, never shared |
| Privacy | Pi-hole fetches blocklists weekly and forwards allowed names upstream. The docs list no telemetry |
Quick tests after every change:
cd ~/docker_volumes/pihole docker compose ps docker logs pihole --tail 50 dig @<server-ip> example.com +short
On Windows use docker compose ps and Resolve-DnsName; on Mac the Linux commands.
What changed in Pi-hole v6#
If your guide mentions WEBPASSWORD, lighttpd, setupVars.conf or pihole -a -p, it describes v5. The last v5 image was 2024.07.0.
- No more lighttpd and PHP. The web server and API are inside
pihole-FTL. - One config file,
/etc/pihole/pihole.toml. - Environment variables use the pattern
FTLCONF_<section>_<setting>. A setting set this way is read-only in the web interface (a lock icon); remove the variable and the default returns. pihole -upandpihole -rare disabled in the container: update by replacing it./etc/dnsmasq.dis not read unless you mount it and setFTLCONF_misc_etc_dnsmasq_d: 'true'.- The image is based on Alpine. The blog says of old variables: "don't expect them to work".
| Old (v5) | New (v6) |
|---|---|
WEBPASSWORD | FTLCONF_webserver_api_password |
PIHOLE_DNS_ | FTLCONF_dns_upstreams (separate with ;) |
DNSMASQ_LISTENING | FTLCONF_dns_listeningMode |
DNSSEC | FTLCONF_dns_dnssec |
WEB_PORT | FTLCONF_webserver_port |
DHCP_ACTIVE | FTLCONF_dhcp_active |
REV_SERVER_* (four variables) | FTLCONF_dns_revServers |
ServerIP, DNS1, DNS2, IPV6, WEB_BIND_ADDR, VIRTUAL_HOST | Removed, no replacement |
Pi-hole or AdGuard Home?#
Both do the same job; pick the one whose settings you will enjoy. Our AdGuard Home guide covers the other one.
| Pi-hole v6 | AdGuard Home | |
|---|---|---|
| Encrypted upstream (DoH/DoT) | Not built in: the docs have guides for helpers (cloudflared, dnscrypt-proxy, Unbound) | Built in |
| Per-device rules | Groups | Client settings |
| Blocking | Subscribed blocklists and allowlists, regex rules | Filter lists, rules |
| DHCP | Built in (host networking in Docker) | Built in |
| Config | One pihole.toml, env vars, web, API | Web and YAML |
Choose Pi-hole for its large community, query log and groups; AdGuard Home when built-in encrypted DNS matters more. The AdGuard column follows our own guide; check its docs for details.
Common mistakes#
| Mistake | Why it happens | Do this instead |
|---|---|---|
Following a v5 guide (WEBPASSWORD, ServerIP) | Old tutorials still rank high; old variables do not work | Use the v6 names in the table above |
| Docker says port 53 is "address already in use" | systemd-resolved holds it on Ubuntu and Fedora | Step 1, the official stub-listener change |
Setting FTLCONF_webserver_api_password: '' | Empty means no password in v6, and since v6.8 a no-password Pi-hole behind a proxy answers 403 (FTL issue 3268; docker-pi-hole issue 2083 thread) | Set a real password from .env |
Leaving out FTLCONF_dns_listeningMode: ALL on the bridge network | The docs say bridge mode needs it; without it other devices get no answers | Keep the line from Step 3, and keep the port off the internet |
Running with --privileged to "fix" things | The README warns users hit problems on 2022.04 and later | Remove it; add only the capability a feature needs (NET_ADMIN for DHCP) |
Auto-updating with Watchtower or latest | The docs say not to. Issue 2085 reports a Synology host out of memory after Watchtower pulled 2026.10.0 | Pin the tag; update by hand after the release notes |
| Pi-hole host uses only Pi-hole for DNS | If the container is down, the host cannot pull images to repair it | Give the host a second, normal DNS (docs, "Catch-22") |
Expecting -p mappings with network_mode: host | Host mode has no port mapping. Issue 1976 shows a reporter confused by port 80 | Remove ports:; move web ports with FTLCONF_webserver_port |
| Changing a setting in the web page and it "locks" or reverts | A setting set by an FTLCONF_ variable is read-only (docs; issue 1978) | Change the variable in .env or compose.yaml, then docker compose up -d |
Mounting /etc/pihole read-only, or no volume | The docs say avoid read-only; without a volume the data is deleted with the container | Use the ./data volume exactly as in Step 3 |
AI assistants: pihole -up inside the container, WEBPASSWORD, ServerIP, version: "3", mounting /etc/dnsmasq.d for everyone | Assistants copy v5 examples | Update with pull, down, up -d; use only the variables on the docs' Configuration page |
Tip: Before pasting any Pi-hole Compose file, check three things: the image tag, the password variable name, and whether it publishes port 53 over TCP and UDP. Those cause most failed setups.
Tip: After any DNS change, run
dig @<server-ip> example.comfrom a second device before you touch your router.
Troubleshooting#
| Problem | Solution |
|---|---|
| Container will not start | docker logs pihole --tail 100; a missing password prints the :? message |
address already in use on 53 | Step 1; check with `sudo ss -lntup |
| Devices time out | Check listeningMode: ALL, the firewall (53 TCP and UDP) and the router's DNS setting |
Page gives 403 Forbidden behind a proxy | Set a password (see the Common mistakes table) |
| Cannot log in | Change the value in .env, then docker compose up -d. With no variable set, the docs say the log prints a "random password" |
| Login does nothing after an update | Reported on 2026.04/2026.05 images (docker-pi-hole 2043); the maintainer linked a Mac browser fix (pi-hole/web 3778). Use the current image; read the browser console (F12) |
| Ads still show on one device | It has another DNS server, IPv6 DNS from the router, or browser secure DNS. Check the Query Log |
| Everything shows one client address | Docker Desktop's network. Run on a Linux host |
| Settings are greyed out | An FTLCONF_ variable controls them |
Error: address already in use#
Older Docker versions print Error starting userland proxy: listen tcp4 0.0.0.0:53: bind: address already in use; newer ones end the same way. Something else holds the port: Step 1.
Warning: Trying to free NULL pointer in readEnvValue()#
WARNING: Trying to free NULL pointer in readEnvValue() appears on FTL v6.9 when a secret variable is set (FTL issue 3356, open on 16 November 2026). The reporter says the password still applies and the warning is cosmetic. Do not remove the password to silence it.
Web interface disappears after a certificate renewal#
On FTL v6.9, a native Raspberry Pi install logged No web server ports configured! and Start of webserver failed! Web interface will not be available! after automatic renewal of the self-signed certificate (FTL issue 3368, open, cause unconfirmed). DNS kept working; a reboot recovered it. In Docker, try docker compose restart pihole and save the log first.
Known bugs (open on 16 November 2026)#
- FTL 3356 and FTL 3368 above.
- docker-pi-hole 2085: a recursive
updatecheck.shon Synology with root mode exhausted memory on2026.10.0. The same cron job's issues 2084 and 2098 are closed;2026.11.0switches tosetpriv, but we could not confirm that fixes 2085. - FTL 3286: a camera fails on long cached CNAME answers.
docker exec pihole pihole reloaddnshelped temporarily.
If something else breaks, read docker logs pihole, then docker exec pihole pihole -v for the component versions, and search the issue tracker for the exact text.
Updates and backups#
Update by hand, never unattended. Read the release notes, back up, change the tag, then run the docs' sequence:
cd ~/docker_volumes/pihole docker compose pull docker compose down docker compose up -d docker logs pihole --tail 30
Repeat the Step 4 tests. Each GitHub release page lists the Core, Web and FTL versions.
Back up the whole data folder plus compose.yaml and .env. The web interface also has Settings, Teleporter, which exports settings and lists but, per the v6.5 notes, not long-term query data. This script stops the container for a few seconds so the databases are consistent:
cd ~/docker_volumes/pihole cat > backup.sh << 'EOF' #!/bin/sh cd "$(dirname "$0")" || exit 1 docker compose stop tar -czf "backups/pihole-$(date +%F).tar.gz" data compose.yaml .env chmod 600 backups/pihole-*.tar.gz docker compose start EOF chmod 700 backup.sh (crontab -l 2>/dev/null; echo "0 3 * * * $HOME/docker_volumes/pihole/backup.sh") | crontab -
That runs it every day at 03:00 on Linux and Mac. DNS pauses for a few seconds, so pick an hour when nobody notices. On Windows, save these lines as backup.ps1 in the same folder and schedule it:
Set-Location "$HOME\docker_volumes\pihole" docker compose stop tar -czf "backups\pihole-$(Get-Date -Format yyyy-MM-dd).tar.gz" data compose.yaml .env docker compose start
schtasks /Create /TN "pihole-backup" /SC DAILY /ST 03:00 /TR "powershell -NoProfile -File $HOME\docker_volumes\pihole\backup.ps1"
Restore test. Never unpack over the live folder:
mkdir -p /tmp/pihole-restore && tar -xzf backups/pihole-<date>.tar.gz -C /tmp/pihole-restore ls /tmp/pihole-restore/data
You should see pihole.toml and gravity.db. To really restore, stop the stack, put the files back, and start it with the same image tag.
Performance and resources#
The docs ask for 512 MB RAM and call Pi-hole "very lightweight". They publish no measured idle figures and neither do we. Measure your own:
docker stats pihole --no-stream
- Query history: kept 91 days by default (
database.maxDBdays); fewer days shrink the database. - DNS cache:
dns.cache.sizedefaults to 10,000; the docs warn that much higher slows lookups. - Busy networks: the docs show
FTL_CMD: no-daemon -- --dns-forward-max 300to raise the concurrent query limit.
FAQ#
Is Pi-hole free? Yes, under the EUPL-1.2. The name and logo are trademarks; see the brand rules before using them.
Does Pi-hole block YouTube or Facebook ads? Often not. It blocks by domain name, and those ads come from the same names as the videos or posts.
Can I run it on a Raspberry Pi? Yes. The Docker Hub tag lists arm64, arm v7 and arm v6, and the docs list Raspberry Pi OS as supported.
Can I use Windows or Mac as the server? Only for testing. The docs do not cover Docker Desktop and DHCP cannot work there.
What if Pi-hole goes down? Everyone loses name lookups. Keep your router's old DNS setting written down; docker compose up -d or a backup brings Pi-hole back.
Sources#
- docker-pi-hole releases 2026.11.0, 2026.10.1 and 2026.10.0, README and LICENSE at the tag - read 16 November 2026
- Pi-hole docs: Docker, Configuration, DHCP, Tips and tricks, Upgrading, v5 to v6, Prerequisites, Post-install, pihole command, FTL configuration, blocking modes, API authentication, upstream providers - read 16 November 2026
- Introducing Pi-hole v6, trademark rules, FTL v6.9, Core v6.6 and Docker Hub tags (tag
2026.11.0and architectures checked) - read 16 November 2026 - Issues: FTL 3268, 3286, 3356, 3368; docker-pi-hole 1976, 1978, 2043, 2083, 2085
- Docker and ufw and Caddy 2.11.9 - read 16 November 2026
Checked against the official docs on 2026-11-16.