DockerSelf-Hosting

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.

Pi-hole official logo

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.

WhatValue (official sources, read 16 November 2026)
Image to pinpihole/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 neededAbout 20 minutes (our estimate, not measured)
Size and RAMThe docs ask for 512 MB RAM and 2 GB free disk (4 GB recommended). Docker Hub lists the tag at about 42 MB compressed
Ports53 TCP and UDP (DNS), 80 and 443 TCP (web page); optional 67 UDP (DHCP) and 123 UDP (NTP)
PlatformsThe Docker Hub tag lists amd64, arm64, 386, arm v7, arm v6 and riscv64
LicenceEUPL-1.2 (the LICENSE file at the release tag). Name and logo are trademarks
Official docsdocs.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-resolved holds 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.

Two-lane diagram: your router hands out Pi-hole as the DNS server, your devices ask it on port 53, and the Pi-hole container blocks listed names and forwards allowed ones to an upstream DNS server; below, you open the admin page through Caddy or Traefik over HTTPS, which proxies to the Pi-hole web port 80, and settings are stored in a data folder on the host

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.

NeedValue
RAM and disk512 MB RAM; 2 GB free disk minimum, 4 GB recommended (prerequisites page)
Linux hosts the docs supportAlpine, Armbian, Debian, CentOS Stream, Fedora, Raspberry Pi OS, Ubuntu (actively maintained versions)
IP addressA fixed address: a DHCP reservation on your router is fine
Ports free53 TCP/UDP and 80/443 TCP on the host (change 80/443 later if needed)
For HTTPS onlyA name for the page (a domain, or a home name with tls internal)

Linux#

Run in terminalbash
docker --version
docker compose version

Windows (PowerShell)#

Run in terminalpowershell
docker --version
docker compose version

Mac (Terminal)#

Same commands as Linux:

Run in terminalbash
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:

Run in terminalbash
sudo ss -lntup | grep ':53 '

If systemd-resolve owns it, use the official method (Pi-hole docs, "Tips and Tricks"):

Run in terminalbash
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:

Run in terminalpowershell
netstat -ano | findstr ":53 "

Mac (Terminal)#

Run in terminalbash
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#

Run in terminalbash
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)#

Codepowershell
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_password empty. 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#

Run in terminalbash
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)#

Codepowershell
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 down and docker compose up -d to 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):

Run in terminalbash
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)#

Codepowershell
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 localhost can 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.

  1. 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.
  2. Pi-hole as the DHCP server. See the next section. Disable your router's DHCP first.
  3. Per device (last resort).

Linux#

With NetworkManager (replace the connection name):

Run in terminalbash
nmcli connection modify "<connection>" ipv4.dns <server-ip> ipv4.ignore-auto-dns yes
nmcli connection up "<connection>"

Windows (PowerShell, as administrator)#

Codepowershell
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ServerAddresses <server-ip>
# undo:
Set-DnsClientServerAddress -InterfaceAlias "Wi-Fi" -ResetServerAddresses

Mac (Terminal)#

Run in terminalbash
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:

File contentyaml
    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:

Run in terminalbash
docker network create proxy

With Traefik#

On a server that already runs Traefik v3 with the Docker provider and an entrypoint named https:

File contentyaml
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:

Run in terminalbash
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):

File contentyaml
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:

File contenttext
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):

File contenttext
pihole.home.arpa {
    tls internal
    reverse_proxy pihole:80
}

Start both stacks, Caddy last:

Run in terminalbash
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):

Run in terminalbash
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 internal and never forward those ports. See our Caddy guide.

Security and testing#

ControlHow
Never expose DNS to the internetlisteningMode: 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 ufwPublished ports skip ufw's rules (Docker docs). Keep the host off the public internet, or bind the DNS lines to <server-ip>
Admin passwordLong, unique, in .env (chmod 600). Pi-hole supports 2FA (TOTP), and scripts can use an application password
No --privileged, no Docker socketThe official example needs neither. Add NET_ADMIN only for DHCP and SYS_TIME only for NTP
Debug outputpihole -d uploads once included password hashes and the TOTP secret; Core v6.6 fixed that. Never post a debug log unread
Backups and .envThey hold secrets and history: chmod 600, never shared
PrivacyPi-hole fetches blocklists weekly and forwards allowed names upstream. The docs list no telemetry

Quick tests after every change:

Run in terminalbash
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 -up and pihole -r are disabled in the container: update by replacing it.
  • /etc/dnsmasq.d is not read unless you mount it and set FTLCONF_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)
WEBPASSWORDFTLCONF_webserver_api_password
PIHOLE_DNS_FTLCONF_dns_upstreams (separate with ;)
DNSMASQ_LISTENINGFTLCONF_dns_listeningMode
DNSSECFTLCONF_dns_dnssec
WEB_PORTFTLCONF_webserver_port
DHCP_ACTIVEFTLCONF_dhcp_active
REV_SERVER_* (four variables)FTLCONF_dns_revServers
ServerIP, DNS1, DNS2, IPV6, WEB_BIND_ADDR, VIRTUAL_HOSTRemoved, 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 v6AdGuard Home
Encrypted upstream (DoH/DoT)Not built in: the docs have guides for helpers (cloudflared, dnscrypt-proxy, Unbound)Built in
Per-device rulesGroupsClient settings
BlockingSubscribed blocklists and allowlists, regex rulesFilter lists, rules
DHCPBuilt in (host networking in Docker)Built in
ConfigOne pihole.toml, env vars, web, APIWeb 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#

MistakeWhy it happensDo this instead
Following a v5 guide (WEBPASSWORD, ServerIP)Old tutorials still rank high; old variables do not workUse the v6 names in the table above
Docker says port 53 is "address already in use"systemd-resolved holds it on Ubuntu and FedoraStep 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 networkThe docs say bridge mode needs it; without it other devices get no answersKeep the line from Step 3, and keep the port off the internet
Running with --privileged to "fix" thingsThe README warns users hit problems on 2022.04 and laterRemove it; add only the capability a feature needs (NET_ADMIN for DHCP)
Auto-updating with Watchtower or latestThe docs say not to. Issue 2085 reports a Synology host out of memory after Watchtower pulled 2026.10.0Pin the tag; update by hand after the release notes
Pi-hole host uses only Pi-hole for DNSIf the container is down, the host cannot pull images to repair itGive the host a second, normal DNS (docs, "Catch-22")
Expecting -p mappings with network_mode: hostHost mode has no port mapping. Issue 1976 shows a reporter confused by port 80Remove ports:; move web ports with FTLCONF_webserver_port
Changing a setting in the web page and it "locks" or revertsA 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 volumeThe docs say avoid read-only; without a volume the data is deleted with the containerUse the ./data volume exactly as in Step 3
AI assistants: pihole -up inside the container, WEBPASSWORD, ServerIP, version: "3", mounting /etc/dnsmasq.d for everyoneAssistants copy v5 examplesUpdate 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.com from a second device before you touch your router.

Troubleshooting#

ProblemSolution
Container will not startdocker logs pihole --tail 100; a missing password prints the :? message
address already in use on 53Step 1; check with `sudo ss -lntup
Devices time outCheck listeningMode: ALL, the firewall (53 TCP and UDP) and the router's DNS setting
Page gives 403 Forbidden behind a proxySet a password (see the Common mistakes table)
Cannot log inChange 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 updateReported 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 deviceIt has another DNS server, IPv6 DNS from the router, or browser secure DNS. Check the Query Log
Everything shows one client addressDocker Desktop's network. Run on a Linux host
Settings are greyed outAn 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.sh on Synology with root mode exhausted memory on 2026.10.0. The same cron job's issues 2084 and 2098 are closed; 2026.11.0 switches to setpriv, but we could not confirm that fixes 2085.
  • FTL 3286: a camera fails on long cached CNAME answers. docker exec pihole pihole reloaddns helped 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:

Run in terminalbash
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:

Run in terminalbash
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:

Codepowershell
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
Run in terminalpowershell
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:

Run in terminalbash
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:

Run in terminalbash
docker stats pihole --no-stream
  • Query history: kept 91 days by default (database.maxDBdays); fewer days shrink the database.
  • DNS cache: dns.cache.size defaults to 10,000; the docs warn that much higher slows lookups.
  • Busy networks: the docs show FTL_CMD: no-daemon -- --dns-forward-max 300 to 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#

Checked against the official docs on 2026-11-16.