docker-pi-hole README

Docker Pi-hole

Network-wide ad blocking via your own Linux hardware

Pi-hole website | Documentation | Discourse Forum | Donate

Upgrade Notes

[!NOTE] Using Watchtower?
See the Note on Watchtower in our documentation.

[!TIP] Some users have reported issues with using the --privileged flag on 2022.04 and above.
TL;DR, don't use that mode, and be explicit with the permitted caps (if needed) instead.

Quick Start

Using Docker-compose:

Copy the below docker compose example and update as needed:

# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      # DNS Ports
      - "53:53/tcp"
      - "53:53/udp"
      # Default HTTP Port
      - "80:80/tcp"
      # Default HTTPs Port. FTL will generate a self-signed certificate
      - "443:443/tcp"
      # Uncomment the line below if you are using Pi-hole as your DHCP server
      #- "67:67/udp"
      # Uncomment the line below if you are using Pi-hole as your NTP server
      #- "123:123/udp"
    environment:
      # Set the appropriate timezone for your location (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g:
      TZ: 'Europe/London'
      # Set a password to access the web interface. Not setting one will result in a random password being assigned
      FTLCONF_webserver_api_password: 'correct horse battery staple'
      # If using Docker's default `bridge` network setting the dns listening mode should be set to 'ALL'
      FTLCONF_dns_listeningMode: 'ALL'
    # Volumes store your data between container upgrades
    volumes:
      # For persisting Pi-hole's databases and common configuration file
      - './etc-pihole:/etc/pihole'
      # Uncomment the below if you have custom dnsmasq config files that you want to persist. Not needed for most starting fresh with Pi-hole v6. If you're upgrading from v5 you and have used this directory before, you should keep it enabled for the first v6 container start to allow for a complete migration. It can be removed afterwards. Needs environment variable FTLCONF_misc_etc_dnsmasq_d: 'true'
      #- './etc-dnsmasq.d:/etc/dnsmasq.d'
    cap_add:
      # See https://docs.pi-hole.net/docker/#note-on-capabilities
      # Required if you are using Pi-hole as your DHCP server, else not needed
      - NET_ADMIN
      # Required if you are using Pi-hole as your NTP client to be able to set the host's system time
      - SYS_TIME
      # Optional, if Pi-hole should get some more processing time
      - SYS_NICE
    restart: unless-stopped

Run docker compose up -d to build and start pi-hole (Syntax may be docker-compose on older systems).

[!NOTE] Volumes are recommended for persisting data across container re-creations for updating images.

Automatic Ad List Updates

cron is baked into the container and will grab the newest versions of your lists and flush your logs. This happens once per week in the small hours of Sunday morning.

Documentation

For more detailed information, please refer to our documentation:

Docker tags and versioning

The primary docker tags are explained in the following table. Click here to see the full list of tags. See GitHub Release notes to see the specific version of Pi-hole Core, Web, and FTL included in the release.

The Date-based (including incremented "Patch" versions) do not relate to any kind of semantic version number, rather a date is used to differentiate between the new version and the old version, nothing more.

Release notes will always contain full details of changes in the container, including changes to core Pi-hole components.

tag	description
`latest`	Always the latest release
`2022.04.0`	Date-based release
`nightly`	Built and pushed whenever there are changes on the `development` branch and additionally produced by the scheduled nightly job. These are the most experimental development images and may change frequently

User Feedback

Please report issues on the GitHub project when you suspect something docker related. Pi-hole or general docker questions are best answered on our user forums

11.7K ·GitHub

Docker-pi-hole

What is this?

This is the official Docker image for Pi-hole, a network-wide ad blocker, letting you run Pi-hole as a container on your own Linux hardware instead of installing it directly on the OS.

Is this an app or just a packaging of an existing tool?

It's a container image that wraps the existing Pi-hole software (Core, Web admin panel, and FTL DNS engine) so you can run it with Docker instead of a bare-metal install.

How do I get it running?

Copy the provided docker-compose example, adjust it to your needs, then run 'docker compose up -d' to build and start the container.

Do I need Docker Compose, or can I use plain docker run?

The quick start is written for docker-compose, noting the command syntax may be 'docker-compose' on older systems; Docker/Docker Compose is the only real prerequisite.

Any install pitfalls I should watch out for?

Avoid using the --privileged flag on versions 2022.04 and above — instead be explicit about which capabilities you actually need.

Will my ad lists stay up to date automatically?

Yes, a cron job baked into the container pulls the newest versions of your ad lists and flushes logs once a week, early Sunday morning.

What do the different Docker tags mean?

'latest' is the newest stable release, date-based tags like '2022.04.0' pin a specific release, and 'nightly' is built from the development branch on every change plus a scheduled nightly job for the most experimental builds.

Where do I report problems with the container itself?

Report Docker-specific issues on the GitHub project; general Pi-hole or Docker usage questions are better suited to the Pi-hole user forums.

Will my settings survive a container update?

Yes, as long as you mount volumes for persistence, your configuration and data survive container re-creation when updating to a new image.

What are similar projects?

pi-hole, anti-AD, esp32-c3-adblock, DnsServer, nginx-proxy-manager, acme.sh, Open-Box, xdp-dns-evadeproxy

Which topics is it in?

pi-hole, docker-container, ad-blocker, self-hosted-ai, cron, homelab, admin-dashboard, dns, shell, proxy, dashboard, web-app

Creator: pi-hole
Size: 2.5 MB
Stars: 11.7K
Updated: CommitOct 17 Release2026.10.0Oct 17
Age: 10y
Commits · 90 Days