The official Pi-hole Docker image from
107 MB
about 2 months ago
Last update
about 2 months ago
about 2 months ago

Docker Pi-hole


Upgrade Notes

  • Using Watchtower? See the Note on Watchtower at the bottom of this readme

  • Due to a known issue with Docker and libseccomp <2.5, you may run into issues running 2022.04 and later on host systems with an older version of libseccomp2 (Such as Debian/Raspbian buster or Ubuntu 20.04, and maybe CentOS 7).

    The first recommendation is to upgrade your host OS, which will include a more up to date (and fixed) version of libseccomp.

    If you absolutley cannot do this, some users have reported success in updating libseccomp2 via backports on debian, or similar via updates on Ubuntu. You can try this workaround at your own risk

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

  • As of 2022.04.01, setting CAP_NET_ADMIN is only required if you are using Pi-hole as your DHCP server. The container will only try to set caps that are explicitly granted (or natively available)

  • In 2022.01 and later, the default DNSMASQ_USER has been changed to pihole, however this may cause issues on some systems such as Synology, see Issue #963 for more information.
    If the container wont start due to issues setting capabilities, set DNSMASQ_USER to root in your environment.

Quick Start

  1. Copy docker-compose.yml.example to docker-compose.yml and update as needed. See example below: Docker-compose example:
version: "3"

# More info at and
    container_name: pihole
    image: pihole/pihole:latest
    # For DHCP it is recommended to remove these ports and instead add: network_mode: "host"
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp" # Only required if you are using Pi-hole as your DHCP server
      - "80:80/tcp"
      TZ: 'America/Chicago'
      # WEBPASSWORD: 'set a secure password here or it will be random'
    # Volumes store your data between container upgrades
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'    
      - NET_ADMIN # Recommended but not required (DHCP needs NET_ADMIN)      
    restart: unless-stopped
  1. Run docker-compose up -d to build and start pi-hole
  2. Use the Pi-hole web UI to change the DNS settings Interface listening behavior to "Listen on all interfaces, permit all origins", if using Docker's default bridge network setting

Here is an equivalent docker run script.

Advanced usage:

See Readme on Github,