On this page (6)
This Pi-hole Docker Compose file runs Pi-hole v6 (image pihole/pihole:2026.10.1, FTL v6.8) as one container with its data in a named volume. You set the web password with the FTLCONF_webserver_api_password variable, which the file reads from a .env file. In our lab it idled at 9.3 MiB (range 9.2 to 9.6) and peaked at 17.9 MiB (17.9 to 18.4) while answering up to 1,000 DNS queries a second, medians of three runs, so by our sizing rule it needs 1 GB of RAM. On Ubuntu the usual snag is port 53: systemd-resolved already listens there, and Docker then refuses to start the container (see “Port 53 is already in use”). We ran the published file with its ports mapped in our sandbox, not in the lab, and the lab runs themselves published no host ports.
Measured readings
Test box: Pi-hole v6 2026.10.1
Measured in our lab on : 3 full runs, each from a fresh stack. Each figure is the median, with the range over the runs under it. The numbers come from the raw result file.
- Idle RAM
- 9 MiBrange 9–10 · 3 runs all containers, median of 3 runs; each run is the mean over 30 s after the stack settled
- Startup peak RAM
- 13 MiBrange 11–14 · 3 runs highest total between healthy and settled
- Peak RAM
- 18 MiBsame when rounded in all 3 runs under load, median of the run peaks
- Settled after
- 121 srange 121–123 · 3 runs after the first healthy response
- Idle CPU
- 0.7 %same when rounded in all 3 runs of one core, lab host
- Startup
- 2.3 srange 1.7–3.5 · 3 runs to first healthy response
- App version
- 2026.10.1
- Tested
- , 3 runs (compose file verified the same day)
- How the figures are made
- Each run starts a fresh stack and goes through setup, settling, the idle window and the load step. We publish the median over the runs and the lowest and highest value, because the lab host and some apps vary from run to run. Runs, median and range
- Lab host
- AMD EPYC 9V74 80-Core Processor, 2 cores, 7.7 GiB RAM, x86_64.Ubuntu 26.04.1 LTS, Docker 29.4.2. Measured in the same GitHub Actions job (run 42159121837) as AdGuard Home; this app was number 1 of 2 in the run order, so an order effect is possible.
- Disk for the images
- About 212 MB with the containerd image store, the default on fresh installs of Docker Engine 29 and later (measured on this lab host, which used the containerd store; never below our estimate of unpacked plus compressed size, plus 10%). Plan for the larger figure. How we size disk
- How idle was measured
- After the stack was healthy and set up, we sampled total RAM until it stayed within max(2% of its mean, 10 MiB) over 60 s (at least 120 s, at most 600 s), then measured idle over the next 30 s. Rule in full
- Peak RAM measured
- Under load. A Python script (standard library only) in a container on the Compose network sends plain UDP DNS queries (type A) to Pi-hole's port 53. The same script and the same 900 names run against AdGuard Home: 500 real popular domains, 300 names from the StevenBlack blocklist that both apps load (so they are blocked and answered 0.0.0.0) and 100 random .com names that do not exist (NXDOMAIN). Three phases, queries sent on a fixed schedule whether or not earlier ones were answered: every name once at 100 queries/s (first-time latency, 9 s); 200 queries/s for 60 s, names drawn in shuffled rounds so most are repeats; then a burst of 1,000 queries/s for 20 s. A query not answered within 2 s is a timeout. The script records queries sent, answered, timeouts, blocked answers and the p50, p95 and p99 latency of first-time and of repeated (cache-expected) queries, and reads the resolver's own query counters before and after. No real clients, no DoH/DoT, no DHCP, no reverse lookups.
| Container | Idle RAM | Peak RAM (under load) | Image, compressed (download) | Image, unpacked (disk, containerd store) |
|---|---|---|---|---|
| pihole | 9 MiBrange 9–10 · 3 runs | 18 MiBsame when rounded in all 3 runs | 43 MB | 149 MB |
Every run (3)
| Run | Idle RAM | Peak RAM | Startup peak | Startup | Lab host CPU |
|---|---|---|---|---|---|
| 1 | 10 MiB | 18 MiB | 14 MiB | 3.5 s | AMD EPYC 9V74 80-Core Processor |
| 2 | 9 MiB | 18 MiB | 13 MiB | 1.7 s | AMD EPYC 9V74 80-Core Processor |
| 3 (closest to median idle) | 9 MiB | 18 MiB | 11 MiB | 2.3 s | AMD EPYC 9V74 80-Core Processor |
0 s to 160 s after healthy; the line spans 0 to 10 MiB. Dashed line: settled.
Timeline as a table
| Seconds after healthy | Total RAM |
|---|---|
| 30 | 9 MiB |
| 60 | 9 MiB |
| 90 | 9 MiB |
| 120 | 9 MiB |
| 150 | 9 MiB |
| 160 | 9 MiB |
RAM is MiB (220 bytes); image sizes are MB (106 bytes). The unpacked column is what our lab host's Docker reported; see Disk for the images for other setups. Per-container peaks happen at different moments, so they do not add up to the total peak. Medians of separate columns need not add up either.
Download verified compose fileDownload .envRaw result JSONHow we measure
Lab notes (6)
- Host: a GitHub Actions runner (ubuntu-latest, x86_64, 2 vCPU, 8 GB RAM; the CPU model varies between runners (AMD EPYC and Intel Xeon models so far) and each run records its own). Not a Raspberry Pi: no Arm result, and the numbers are valid for that host only.
- Measured: idle RAM and CPU after start-up with the default list loaded and no client; RAM and CPU while one client sends the DNS load of load.description (200 queries/s for 60 s, then 1,000 queries/s for 20 s); image size; start-up time; answer latency seen by that client. Not measured: real clients or a real household's query mix, DNS-over-HTTPS or DNS-over-TLS, DHCP, IPv6, DNSSEC validation, long-term growth of the query database, adlists beyond the default one, Arm hardware.
- Fair comparison: both apps use the same upstream resolver (1.1.1.1, plain UDP), the same single blocklist (StevenBlack unified hosts, Pi-hole's default list) and the same blocking answer (0.0.0.0). The upstream resolver's response time varies from run to run, so the first-time latency (which includes it) is not comparable between runs or apps; the latency of repeated queries that the resolver should answer from its cache is. The script counts a repeat as cache-expected when an earlier answer for that name arrived less than half its TTL ago.
- Settings changed from the app's defaults, in setup: upstream 1.1.1.1 (default 8.8.8.8 and 8.8.4.4) and the rate limit off (default 1,000 queries per 60 s per client). Left at default: query logging on, cache size 10,000 entries, DNSSEC off, blocking mode NULL. Settings in the published compose: listening mode ALL (needed on Docker's bridge network), password, time zone.
- The 'domains loaded' figure is Pi-hole's gravity count (unique domains after de-duplication). AdGuard Home reports rules, which also count a few non-domain lines of the hosts file; the two numbers are close but not the same quantity.
- Lab-only compose override compose.lab.yaml (NOT in the published compose): The lab run publishes no host ports (53, 80 and 443 of the published file are not mapped): the runner's systemd-resolved listens on 127.0.0.53:53 and Docker's port 53 publishing can clash with it, and the setup and load steps reach Pi-hole by service name over the Compose network instead. Image, environment, volume and capabilities are the published file's. The published file has not been run with its ports mapped in the lab.
Tested 2026.10.1. The 2026.10.1 release (Oct 31, 2026, read again on Nov 4) updates the Alpine base image to 3.24.3 and makes scheduled nightly builds skip the layer cache. Its notes say the update picks up fixes for high-profile CVEs in Alpine and that it likely does not affect Pi-hole, and they list no Pi-hole component versions and no security advisories. The release before it, 2026.10.0 (Oct 17, 2026), was the security release: it “includes fixes for 17 security advisories across FTL, Web and Core”, five of them High, and lists no breaking changes. If you run 2026.09.0 or older, update to 2026.10.1 (at least 2026.10.0). The lab reported FTL v6.8 on 2026.10.1, as on 2026.10.0; it did not report the Web and Core versions. FTL v6.8 itself lists some behavior changes (FTL v6.8 notes): invalid values in pihole.toml are reset to defaults, a renewed self-signed certificate comes with a new CA so an imported tls_ca.crt must be imported again, and queries older than database.maxDBdays are purged on the first night after start-up. We did not test any of the advisories and say nothing about whether your setup is exposed. To move a stack that pins an older tag, change the tag on the image: line and run:
Not run in our lab: an upgrade of a running stack. We started fresh 2026.10.1 stacks.
docker compose pull
docker compose up -dVerified compose file
One service, pihole, and one named volume, pihole-etc, for Pi-hole’s databases, lists and settings. The file follows the Quick Start in the docker-pi-hole README and the Docker pages of the Pi-hole docs, with four differences, all marked in the file’s comments: the image tag is pinned (the README uses latest), the password comes from .env, the data is in a named volume instead of ./etc-pihole, and only the SYS_NICE capability is added. The README example also adds NET_ADMIN and SYS_TIME; the docs say NET_ADMIN is “Required if you are using Pi-hole as your DHCP server, else not needed” and SYS_TIME is needed only if Pi-hole sets the host’s clock as an NTP client, so both are left out (DHCP is covered below).
# Verified compose for Pi-hole v6, tested 2026-11-06 by the SelfHostBench lab (3 runs; the figures are the median).
# Lab host: AMD EPYC 9V74 80-Core Processor, 2 vCPU, 7.7 GiB RAM, x86_64, Docker 29.4.2.
# Floating image tags below were replaced by the version resolved at test time;
# the registry digest is in the comment on each image line.
# Measurements: pihole.json (schema 3).
# Lab difference: The lab run publishes no host ports (53, 80 and 443 of the published file are not mapped): the runner's systemd-resolved listens on 127.0.0.53:53 and Docker's port 53 publishing can clash with it, and the setup and load steps reach Pi-hole by service name over the Compose network instead. Image, environment, volume and capabilities are the published file's. The published file has not been run with its ports mapped in the lab.
# Companion env file: pihole.env (save it as .env next to this file).
# Secrets are not published: the lab's values are public. In pihole.env:
# PIHOLE_PASSWORD is commented out. Uncomment it and set your own value (the comment above it explains how).
# Pi-hole v6 (official image pihole/pihole) in Docker Compose: a network-wide DNS ad blocker.
# Follows the Quick Start of https://github.com/pi-hole/docker-pi-hole (README, tag 2026.10.1) and
# https://docs.pi-hole.net/docker/configuration/ . Differences from the README example, each marked below:
# the image tag is pinned, the password comes from .env, the data lives in a named volume, and only
# the capability Pi-hole needs without DHCP or NTP is added.
# There is no TLS in front of the web interface except the self-signed certificate Pi-hole makes for port 443.
# Do not expose ports 53 or 80 to the internet: an open resolver is used for DDoS reflection.
name: pihole
services:
pihole:
image: pihole/pihole:2026.10.1 # sha256:30f803ad5dd60ff96cc0a63008a2e9271af481c1b0399a182192b2e91152c1f9 (version 2026.10.1, from label:org.opencontainers.image.version)
restart: unless-stopped
ports:
# DNS, for the devices on your network. If the host's own DNS (systemd-resolved on Ubuntu and Debian)
# already listens on port 53, Docker cannot bind it: see "Port 53 is already in use" in the article.
- "53:53/tcp"
- "53:53/udp"
# Web interface and API over HTTP, and over HTTPS (FTL generates a self-signed certificate).
# Change the left-hand numbers if another service on the host already uses 80 or 443.
- "80:80/tcp"
- "443:443/tcp"
# Add these only if you use Pi-hole as the DHCP server (it also needs NET_ADMIN below) or as an NTP server:
#- "67:67/udp"
#- "123:123/udp"
environment:
# Your time zone (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones): logs rotate at local midnight.
TZ: "America/New_York"
# Password for the web interface and the API. Set in .env; without one Pi-hole would assign a random password.
FTLCONF_webserver_api_password: "${PIHOLE_PASSWORD:?set PIHOLE_PASSWORD in .env}"
# Docker's default bridge network: Pi-hole must answer queries that arrive from outside its own subnet.
# Without this, v6 ignores them. (README: "should be set to 'ALL'".)
FTLCONF_dns_listeningMode: "ALL"
volumes:
# Pi-hole's databases, lists and settings (pihole.toml). Back this volume up before an upgrade.
- pihole-etc:/etc/pihole
cap_add:
# Optional: lets Pi-hole get more processing time. The README example also lists NET_ADMIN (only for DHCP)
# and SYS_TIME (only if Pi-hole should set the host's clock over NTP); they are left out here.
- SYS_NICE
volumes:
pihole-etc:What the settings do:
image: pihole/pihole:2026.10.1is pinned, with the tested digest in a comment. A floating tag changes the next time you pull.53:53on TCP and UDP is DNS for the devices on your network.80and443serve the web interface and the API; Pi-hole makes a self-signed certificate for 443. The DHCP (67/udp) and NTP (123/udp) ports are commented out.TZis set toAmerica/New_Yorkin the file: change it. The docs say setting it makes logs rotate at local midnight instead of UTC midnight.FTLCONF_webserver_api_passwordis the web interface and API password, taken from.env. Compose stops with the message in the file ifPIHOLE_PASSWORDis unset.FTLCONF_dns_listeningMode: "ALL"is there because of Docker’s default bridge network (see “Listening mode” below).SYS_NICEis optional; the docs say “Optional, if Pi-hole should get some more processing time”. The container’s log still prints aCAP_SYS_TIME is not availablewarning at start because the file does not grantSYS_TIME. We did not test NTP.
The .env holds one commented-out line:
# Password for the Pi-hole web interface and API. Choose your own; the stack does not start without it.
# A placeholder would become a real, known password, so the lab's value is not published and this line is commented out.
# Generate one with: openssl rand -hex 16
# PIHOLE_PASSWORD=The published .env has no password, on purpose. The lab ran with its own password, but it sits in our public test config. Pi-hole accepts any text as the password, so a placeholder left in place would become a known password. The line is commented out, and the compose file refuses to start until you set your own. This also means the files you download are not byte for byte the files the lab ran: the .env has the lab’s value removed, and the compose file has a block of comment lines at the top (what was tested, on which host, and how the lab run differed) and the image digest as a comment on the image: line.
Install steps
We ran these in a scratch folder in our sandbox on Oct 31, 2026 (Docker 29.6.2, Compose 5.3.1, Ubuntu 24.04), with the same image digest as the lab. The raw output is in lab/notes/pihole-compose-2026-10-31.md in the lab repository. The sandbox could not download the blocklist (its proxy intercepts TLS, and the container does not trust the proxy’s certificate), so Pi-hole ran with an empty list there. Nothing below shows ad blocking; the lab measured that.
-
Install Docker Engine with the Compose plugin.
-
Make a folder and save the two files above as
compose.yamland.envin it. The download links are on each block. SetTZincompose.yaml. -
Make a password and put it in
.env: remove the#and paste the value afterPIHOLE_PASSWORD=.openssl rand -hex 16prints 32 hex characters (the command comes from the file’s own comment).bash openssl rand -hex 16 -
Start the stack. The first start downloads the image (42.9 MB compressed, see below) and builds the blocklist database.
--waitreturns when the container reports healthy.bash docker compose up -d --waitIn the sandbox this returned healthy after 31 s on the first start (with the failed list download described above). The lab’s health check, which is the web API answering, passed 1.6 s after
docker compose up -din two runs and 4.2 s in the third. -
Check the container and its ports.
bash docker compose ps --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'Our output:
text NAME STATUS PORTS pihole-pihole-1 Up 31 seconds (healthy) 0.0.0.0:53->53/tcp, 67/udp, 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:53->53/udp, 123/udp67/udpand123/udpare listed as container ports with no host mapping: they are not published. -
Open
http://<host>/admin/and log in with your password. In the sandbox/admin/answered with a redirect to/admin/loginover HTTP and HTTPS, and/answered 404. The HTTPS certificate is self-signed (curlwithout-kfails verification), so your browser will warn once. Our scripts logged in through the API instead of a browser: the right password returned HTTP 200 and a valid session, a wrong one returned 401. Not run in our lab: the browser login. -
Ask Pi-hole for a name from another machine. Not run in our lab:
digandnslookupwere not installed in our sandbox, so we sent the same kind of query (a UDP A query forexample.org) with a Python script to the published port and got an answer with two addresses.bash dig @<host-ip> example.org -
Point your devices at the host. The Pi-hole docs (post-install) say to configure your router to have DHCP clients use Pi-hole as their DNS server, and that setting each device by hand is a last resort. The same page warns that if the host itself uses Pi-hole for DNS and Pi-hole fails, the host loses name resolution. Not run in our lab: any router or client setting.
To stop the stack, docker compose down removes the container and keeps the volume (down -v deletes it, with your settings and lists). We checked that settings survive: we changed the upstream through the API, ran docker compose down and docker compose up -d --wait, and the new value was still there.
Measured resources
Source: pihole.json, three runs on Nov 6, 2026, each from a fresh stack, on a GitHub Actions ubuntu-latest runner (2 vCPU AMD EPYC 9V74, 7.7 GiB RAM, Ubuntu 26.04.1, Docker 29.4.2 with the containerd image store). The runs were made in the same job as the AdGuard Home runs (run order Pi-hole, then AdGuard Home), which is what the comparison page uses; that page also has the pair run the other way round on Nov 5. The Nov 3 runs were on an Intel Xeon Platinum 8573C and the Oct 19 runs of 2026.10.0 on an AMD EPYC 9V74 with Ubuntu 24.04.5 and Docker 28.0.4 (overlay2), so CPU and image-store differences are mixed in with the version when you compare with those. The lab run used an override with no published ports, because the runner’s systemd-resolved owns 127.0.0.53:53 and the lab reached Pi-hole by service name over the Compose network; image, environment, volume and capabilities were the published file’s. Every figure is the median of the three runs, with the lowest to highest run in brackets (why we repeat runs). Idle is the mean of 30 s after the total memory had settled, with the default list loaded and no client. The load was one Python client on the Compose network: every one of 900 names once at 100 queries/s, then 200 queries/s for 60 s, then 1,000 queries/s for 20 s, 32,900 queries per run, with the default upstream replaced by 1.1.1.1 over plain UDP and the query rate limit switched off (test method). Peak is the highest total sample during the load.
| Measure | Pi-hole 2026.10.1 | Source |
|---|---|---|
| Idle RAM, MiB | 9.27 (9.22 to 9.59) | Tested |
| Startup peak RAM, MiB (healthy to settled) | 12.52 (11.34 to 13.70) | Tested |
| Peak RAM under load, MiB (up to 1,000 queries/s) | 17.94 (17.86 to 18.44) | Tested |
| RAM reading used for sizing (highest run), MiB | 18.44 | Tested |
| Idle CPU, % of one core, lab host | 0.67 (0.66 to 0.67) | Tested |
| CPU during the load, mean, % of one core, lab host | 5.21 (3.79 to 5.66) | Tested |
| Queries sent, answered, timeouts (2 s limit) | 32,900, 32,898 to 32,899, 1 to 2 per run (and 5 SERVFAIL answers per run) | Tested |
| Blocklist loaded (StevenBlack unified hosts, Nov 6 snapshot) | 77,759 domains (Pi-hole’s gravity count) | Tested |
Healthy after docker compose up -d, s |
2.3 (1.7 to 3.5) | Tested |
| Image, compressed / unpacked, MB | 42.9 / 149 (containerd store) | Tested |
What the numbers say:
- By our sizing rule (how we size) it needs 1 GB. The highest run reading, 18.4 MiB, times 1.5 is 28 MiB. That is the smallest tier we use, so the rule cannot say how much less would do. We did not test a host below 1 GB or a memory limit on the container.
- Docker’s idle figure is a working-set number, and it is low. It depends on what the page cache holds: a sandbox check on the 2026.09.0 image (Oct 14) read 12.2 MiB with a warm page cache and 56.7 MiB right after the cache was dropped. The details are in what the idle RAM figure includes.
- CPU and startup times are for the lab host only. The runner’s CPU model changes between runs of the whole lab; all three Pi-hole runs here were on one model, an AMD EPYC 9V74 (the Nov 3 runs were on an Intel Xeon Platinum 8573C, the Oct 19 runs of 2026.10.0 on an EPYC 9V74 as well). Idle CPU read 0.67% here, 0.81% in the Nov 5 job on the same CPU model, 0.73% on the Xeon and 0.18% on the Oct 19 EPYC runs, and CPU during the load was 5.2% here and 7.0% on Nov 5, so we do not credit the differences to the version.
- Almost every query was answered; the exceptions were in the first pass. In each run 1 to 2 of 32,900 queries got no answer inside the 2 s limit (always in the first pass over the 900 names; none in the 200 and 1,000 queries/s phases) and 5 got SERVFAIL. The timeout was
www.bitgratitudesolution.comin all three runs (a name from the test’s blocklist group, which the Nov 6 list no longer holds, so it went to the upstream), plushku.hkin run 2. The SERVFAIL names were the same five in every run (domowysklad.pl,ih7mkw.qpon,pl-53198975.shop,www.albioncredmere.sbs,www.qubitrade-ai.click), all from that group, and AdGuard Home returned SERVFAIL for the same five in the same job. This is not the usual result of the pair: in the Nov 5 job, on the same CPU model, Pi-hole left 41 to 47 queries per run unanswered, all in the first pass, and so did AdGuard Home (31 to 41 in its first pass). Both apps moved together between the two jobs, so we put the difference on the runner or its path to 1.1.1.1 on the day and not on Pi-hole; we did not trace it. One client with one query mix says nothing about a household’s traffic. - The list changed under the test. The lab fetches the StevenBlack list when it runs. It held 77,759 domains on Nov 6, Nov 5 and Nov 3 (71,493 on Oct 19, 72,526 on Oct 13), and 7,800 to 7,815 answers per run were blocked (8,140 to 8,198 on Nov 5, 7,795 to 7,799 on Nov 3, 9,581 on Oct 19; the count depends on the shuffled order of the repeated queries as well as on the list). RAM did not follow the list: idle was 9.27 MiB on a list of 71,493 domains and 9.21 to 9.35 MiB on 77,759, on different CPUs and hosts, so we claim no link.
- Disk. The Test box gives the image size on both Docker image stores. Your data (the query log and the gravity database) comes on top, and we did not measure its growth over days.
What we did not measure: real clients, DNS-over-HTTPS or -TLS, IPv6, DNSSEC validation, DHCP leases, blocklists beyond the default one, and Arm hardware such as a Raspberry Pi. For RAM and latency against AdGuard Home, measured in the same job on one CPU model, in both run orders, see AdGuard Home vs Pi-hole v6.
Gotchas, upgrade and backup
The checks in this section were run once in our sandbox on Oct 31, 2026, on image 2026.10.0 (not repeated on 2026.10.1), unless a line says “researched”. The sandbox is not the lab runner: 4 vCPUs, Docker 29.6.2, cgroup v1.
Port 53 is already in use
On Ubuntu and Debian desktops and servers that use systemd-resolved, its stub listener sits on 127.0.0.53, port 53 (the resolved.conf manual says the stub listens on addresses 127.0.0.53 and 127.0.0.54, port 53). A container that publishes 53:53 binds 0.0.0.0:53, which collides with it. Our sandbox has no systemd-resolved, so we held 127.0.0.53:53 with a small Python process instead, on UDP and TCP. With that running, docker compose up -d printed this and left the container created and not started:
Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint pihole-pihole-1 (957c670f...): failed to bind host port 0.0.0.0:53/tcp: address already in useThe Pi-hole docs cover this clash on their Docker tips and tricks page (“Disable systemd-resolved port 53”; read Oct 31, 2026), which was not part of the Quick Start we followed. There are two ways out.
Bind Pi-hole to one address of the host. Compose’s short port syntax takes an optional IP before the host port, and the docs warn that leaving it out binds all interfaces. Use your host’s LAN address in both DNS lines, and leave the others alone:
ports:
- "192.168.1.10:53:53/tcp"
- "192.168.1.10:53:53/udp"We ran this with the sandbox’s own address while the stand-in held 127.0.0.53:53: the container came up healthy, docker compose ps showed the two port 53 bindings on that address (192.0.2.2 in the sandbox), and a query to that address was answered. Replace 192.168.1.10 in the lines above with your host’s address; it should not change, so give the host a fixed address or a DHCP reservation. Devices then use that address as their DNS server.
Turn the stub listener off. The Pi-hole docs’ page above describes the same three steps (a drop-in file that turns the stub listener off, /etc/resolv.conf pointed at the file systemd-resolved generates under /run/systemd/resolve/, a restart of the service). The commands below are adapted from AdGuard Home’s Docker wiki, which gives them for the same clash (the page carries a notice from its authors that it is outdated); they differ from the Pi-hole page by keeping a backup of the old resolv.conf instead of deleting it. We left out the wiki’s DNS=127.0.0.1 line, because that line makes the host itself use the app on port 53 and the Pi-hole docs warn about losing DNS if Pi-hole is down. The systemd-resolved manual describes /run/systemd/resolve/resolv.conf as listing all known DNS servers, so clients that read it bypass the stub. Not run in our lab: our sandbox has no systemd-resolved, and we left the lab runner’s as it was.
sudo mkdir -p /etc/systemd/resolved.conf.d
printf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/pihole.conf
sudo mv /etc/resolv.conf /etc/resolv.conf.backup
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl reload-or-restart systemd-resolvedTo see what holds the port first, a Pi-hole forum answer (port 53 in use, a user post, not official docs) suggests sudo lsof -i -P -n | grep LISTEN. Check before you assume it is systemd-resolved: a reader in that thread still had a conflict after the change, with dnsmasq on another address.
The web password
Set FTLCONF_webserver_api_password, as the file does. The docs say that if it is not set and no password was configured before, a random password is generated and written to the log, and that setting it to an empty string sets no password. We removed the variable and started the stack: the log held No password set in environment or config file, assigning random password: <8 characters>, so docker logs pihole-pihole-1 finds it. With the variable set, the right password logged in through the API and a wrong one returned 401.
Two more results:
pihole setpasswordand the variable do not mix. With the variable set,docker exec <container> pihole setpassword <new>printedwebserver.api.password set by environment variable. Please unset it to use this function, and the old password still worked. Change the value in.envand recreate the container instead.- Without the variable,
pihole setpasswordworks, with a delay. It printedNew password set. A login with the new password returned 401 at once and 200 about 10 seconds later, and the new password also worked afterdocker compose restart. The command is described on the docs’ pihole command page.
The docs also describe WEBPASSWORD_FILE for Docker secrets, to keep the password out of the Compose file. Not run in our lab.
Settings as environment variables, and upstream DNS
The configuration page gives the pattern FTLCONF_[section_][setting]: the TOML setting dnssec in the [dns] section becomes FTLCONF_dns_dnssec. Lists are separated with semicolons. A setting given this way becomes read-only: “you will not be able to change them via the web interface or CLI”, and if you remove the variable later it goes back to the default.
For the upstream resolvers this matters, because the image’s default is Google DNS. We read the default from a fresh stack’s API: ["8.8.8.8", "8.8.4.4"]. To use others, add one line under environment:. This is not the published file; we ran it as a variant:
FTLCONF_dns_upstreams: "1.1.1.1;1.0.0.1"The API then returned ["1.1.1.1", "1.0.0.1"], and trying to change the value through the API failed with HTTP 400 and Config items set via environment variables cannot be changed via the API. Settings you change in the web interface or API without a variable are kept in the pihole-etc volume and survived docker compose down and up.
Coming from v5: the environment variables changed
The docs (Upgrading from v5.x) say the last image with v5 components was 2024.07.0, later images are v6, and “Nearly all environment variables from previous versions have been removed”: use the FTLCONF_ equivalent instead. The main ones, as the page lists them:
| v5 variable | v6 variable |
|---|---|
WEBPASSWORD |
FTLCONF_webserver_api_password |
PIHOLE_DNS_ |
FTLCONF_dns_upstreams |
DNSMASQ_LISTENING |
FTLCONF_dns_listeningMode |
DNSSEC |
FTLCONF_dns_dnssec |
INTERFACE |
FTLCONF_dns_interface |
QUERY_LOGGING |
FTLCONF_dns_queryLogging |
CUSTOM_CACHE_SIZE |
FTLCONF_dns_cache_size |
WEB_PORT |
FTLCONF_webserver_port |
DHCP_ACTIVE, DHCP_START, DHCP_END, DHCP_ROUTER, DHCP_LEASETIME |
FTLCONF_dhcp_active, _start, _end, _router, _leaseTime |
REV_SERVER* (several variables) |
one FTLCONF_dns_revServers |
The page also lists variables removed with no replacement, among them DNS1, DNS2, IPV6, ServerIP, VIRTUAL_HOST and WEB_BIND_ADDR. Two notes from the page and the compose example in the docs: Pi-hole v6 no longer reads /etc/dnsmasq.d/ by default (mount the folder and set FTLCONF_misc_etc_dnsmasq_d: 'true' to restore it), and the docs’ example says to keep that mount for the first v6 start of a v5 upgrade “to allow for a complete migration”.
We checked one of these on 2026.10.0. With WEBPASSWORD: "..." in place of the new variable, Pi-hole ignored it: the log said it was assigning a random password, and a login with the v5 value returned 401. An old file that sets WEBPASSWORD therefore starts with a password you did not choose. We did not run a v5 to v6 migration. Our comparison page quotes the v6 announcement, which calls the upgrade one-way: back up first.
DHCP and the NET_ADMIN capability
The published file does not run Pi-hole’s DHCP server. For that, the docs say NET_ADMIN is required, and the DHCP page calls host networking “Possibly the simplest way to get DHCP working with Docker Pi-hole”, while in bridge mode you need a DHCP relay pointing at the container’s port 67. We tried the first half. We added FTLCONF_dhcp_active: "true" and a made-up address range to the published file, without NET_ADMIN: docker compose up -d --wait reported the container unhealthy, and its log said:
ERROR: DHCP requested but NET_ADMIN is not available. DHCP will not be started.
Please add cap_net_admin to the container's capabilities or disable DHCP.With - NET_ADMIN added under cap_add: the same file came up healthy. We did not test host networking, a relay, or whether a client got a lease.
Listening mode: why the file sets it to ALL
The README example says: “If using Docker’s default bridge network setting the dns listening mode should be set to ‘ALL’”. Without the variable, our stack reported LOCAL as its mode. We could not reproduce a refusal. A query from the host and one from a container on another bridge network were both answered with LOCAL. The query log shows why they looked local: Pi-hole recorded both as coming from 172.19.0.1, the gateway of its own Compose network, not from the sender. A device on your LAN may arrive with its own address instead; we had no second machine and did not test it. So the comment in the file (“Without this, v6 ignores them”) is the README’s advice, not something we confirmed. We would keep ALL, as the docs say, and keep port 53 off the internet: the file’s header warns that an open resolver is used for DDoS reflection.
Ports 80 and 443
If another service on the host already uses 80 or 443, change the left-hand numbers, for example "8080:80/tcp". The Caddy in our Vaultwarden Docker Compose guide publishes 80, 443 and 443/udp, so the two files clash on one host. We did not run them together.
Update and back up
The file pins an exact tag, so an update is an edit: change the tag, delete the stale digest comment after it, then run the two commands at the top of this page. We did not run an upgrade of a stack with data. All state is in the pihole-etc volume. After the first start it held pihole.toml, gravity.db, pihole-FTL.db, the TLS files and config_backups, among others. The file’s comment says to back it up before an upgrade. We did not test a backup or a restore.
What we did not measure
- The published file with its ports mapped in the lab: the lab run used a no-ports override. We ran the published file with ports once in the sandbox, with an empty blocklist.
- Ad blocking in the sandbox, real clients, DoH or DoT, IPv6, DNSSEC, and a household’s query mix.
- A v5 to v6 migration, DHCP leases, NTP, a reverse proxy in front, and the systemd-resolved steps on a real Ubuntu host.
- Arm hardware (a Raspberry Pi) and memory or database growth over days.
Where to run it
- Hardware. Pi-hole v6 idled at 9 MiB and peaked at 18 MiB under load (medians of 3 runs) in our lab. The highest reading in any run was 18 MiB. Plan for at least 1 GB of RAM, sized from the highest run. See how much RAM self-hosted apps use.
- VPS. The smallest plan that runs this comfortably has 1 GB of RAM, plus disk for your data and the images. Plan for about 212 MB for the images (Docker's containerd image store, the default on fresh installs of Docker 29 and later).
- Keep it safe. Back up the data volume before you rely on it, and put the app behind a reverse proxy with HTTPS before you expose it to the internet. See backing up self-hosted apps.
How we size: recommended RAM is the highest reading in any of our runs (under load or during startup, not the median) times 1.5, rounded up to the next of 1, 2, 4, 8, 16 or 32 GB. The extra half covers the operating system, Docker, file cache and spikes our sampling can miss. Your own data and extra apps need more. Disk for images: Docker Engine 29 and later uses the containerd image store on fresh installs, which keeps each image twice (as downloaded and unpacked); older installs use overlay2, which keeps it unpacked only. We plan for the larger figure: unpacked plus compressed size, plus 10%, rounded up. Your data volumes and growth come on top.
Related
- The same container next to its main alternative, with RAM, CPU and answer latency side by side and a researched feature table: AdGuard Home vs Pi-hole v6. Pick AdGuard Home there if you want encrypted DNS served by the app itself.
- Another small always-on stack, with Caddy providing the HTTPS and the same port 80 and 443 caveat: Vaultwarden Docker Compose.
- How much RAM a box needs for Pi-hole plus other apps, from the same lab method: how much RAM self-hosted apps need. Another single-container monitor for the same box: Uptime Kuma Docker Compose.
- How the lab measures RAM, CPU and image sizes: methodology. Other apps in this format: the self-hosted apps index.
- Official sources used on this page, read Oct 31, 2026 (the 2026.10.1 release page again on Nov 4): the docker-pi-hole README and the Pi-hole docs on Docker, configuration, upgrading from v5, DHCP, tips and tricks, post-install and the pihole command; the release pages of docker-pi-hole 2026.10.1, 2026.10.0 and FTL v6.8 (read through a web-fetch tool); the systemd resolved.conf and systemd-resolved manuals; AdGuard Home’s Docker wiki; and Docker’s Compose services reference.
Update log
- Pi-hole 2026.10.1 re-measured on Nov 6, 2026 (three runs), in the same GitHub Actions job as AdGuard Home v0.107.79, on an AMD EPYC 9V74 (Ubuntu 26.04.1, Docker 29.4.2, containerd store); the Nov 3 runs were on an Intel Xeon Platinum 8573C. Pi-hole ran first in this job. A job of Nov 5 ran the pair the other way round (AdGuard Home first, Pi-hole second) and is compared on the AdGuard Home page and in lab/notes/dns-pairs-2026-11.md. Idle 9.27 MiB (range 9.22 to 9.59; was 9.35; 9.21 in the Nov 5 job), startup peak 12.52 MiB (was 12.30), peak 17.94 MiB (17.86 to 18.44; was 18.24; 18.05 on Nov 5), idle CPU 0.67% of one core (was 0.73%), CPU during the load 5.21% (was 4.23%, other CPU), healthy after 2.3 s (was 2.2). The sizing figure is 18.4 MiB and the tier is still 1 GB. The list was 77,759 domains again (same as Nov 3 and Nov 5), 212 of the 300 blocklist test names were blocked. 1 to 2 of 32,900 queries per run got no answer within 2 s (all in the first pass) and 5 got SERVFAIL (the same names as AdGuard Home's in the same job). The Nov 5 job, on the same CPU model, had 41 to 47 timeouts per run for Pi-hole and 31 to 41 in the first pass for AdGuard Home; we read that as the runner or its path to 1.1.1.1 on that day and not as something about Pi-hole, and did not trace it.
- Re-tested on Pi-hole 2026.10.1 (was 2026.10.0), a precaution release of Oct 31 that updates the Alpine base image to 3.24.3 and lists no advisories, median of 3 runs on Nov 3. The runner changed: an Intel Xeon Platinum 8573C (the 2026.10.0 runs were on an AMD EPYC 9V74), Ubuntu 26.04.1 and Docker 29.4.2 with the containerd image store (was Ubuntu 24.04.5, Docker 28.0.4, overlay2), so we claim no cause for the RAM figures. Idle 9.35 MiB (range 9.31 to 9.43; was 9.27), startup peak 12.3 MiB (was 11.7), peak 18.24 MiB (17.92 to 18.82; was 18.18), idle CPU 0.73% of one core (was 0.18%, other CPU), CPU during the load 4.2% (was 4.5%). The sizing figure is 18.8 MiB and the tier is still 1 GB. Image download 42.9 MB (unchanged); unpacked 149 MB, the containerd store's figure (was 99.5 MB on overlay2). Two things in the load result changed and are not about Pi-hole's memory: the live-fetched StevenBlack list grew to 77,759 domains (was 71,493), so 212 of the 300 blocklist test names were blocked (was 262) and 7,795 to 7,799 answers per run were blocked (was 9,581); and 1 to 2 queries per run got no answer within 2 s and 4 got SERVFAIL (was 0 and 0), almost all on names from the test's blocklist group, with 1.1.1.1 as the upstream; we did not look into why. Replaces the notice that 2026.10.1 was untested; the release page was re-read on Nov 4. The sandbox checks (published file with ports, variants, the v5 variable table) ran on 2026.10.0 on Oct 31 and were not repeated.
- First published. Pi-hole 2026.10.0 (FTL v6.8, Web v6.6.1, Core v6.5): the measured figures are the lab's three runs of Oct 19, 2026 on a GitHub Actions runner, which published no host ports. The published file itself, with its ports mapped, and the variants on this page were run once in our sandbox on Oct 31 (raw output in lab/notes/pihole-compose-2026-10-31.md); the sandbox could not download the blocklist, so no blocking was checked there. Pi-hole 2026.10.1, released the same day, is newer than what we tested and is not run. The facts about environment variables, the v5 to v6 mapping, capabilities and DHCP are from the official documentation, read Oct 31, 2026.