Pihole Docker: How to Install and Run Pihole Using Docker

Online ads and trackers can really clutter your browsing experience, slow down the network, and even compromise on privacy. Pihole Docker offers an incredible solution by acting as a network-wide ad blocker that filters unwanted traffic before it reaches your devices. 

Running Pihole via Docker containers makes the entire setup and management even simpler. With Docker, you can deploy Pihole in a lightweight and isolated environment without altering your system configurations. It is quite easy to update, back up, and move between machines, which is ideal for at home users and system administrators. 

In this guide, you will learn how to install, configure, and manage Pihole using Docker and Docker Compose. 

What Is Pihole and Why Use It with Docker?

Pihole Docker is a network wide ad blocker extension that acts as a DNS sinkhole, intercepting DNS sinkhole, incepting DNS queries and blocking requests. It helps speed browsing, reduces the bandwidth usage, and improves privacy across all devices. 

Running Pihole Docker simplifies deployment and management. Therefore, instead of installing Pihole directly to the system, Docker runs it in an isolated environment that is easy to set up, update, and remove. 

Key benefits of using Pihole in Docker include:

• Quick setup with minimal dependencies
• Easy updates through Docker images
• Consistent behavior across environments
• Compatibility with Docker Compose for automation and scaling

Prerequisites for Pihole Docker Installation

Before you set up Pihole Docker, make sure that your system fulfills the following requirements: 

• Operating System: A Linux-based system (Ubuntu, Debian, or similar) with Docker installed.
• Docker & Docker Compose: Latest stable versions installed and running.
• Static IP Address: Recommended for consistent DNS behavior on your network.
• Port Availability: Ports 53 (DNS) and 80 (web dashboard) must be open and not used by other services.
• Sudo or Root Access: Required to manage containers and network configurations.
• Dedicated DNS settings in your router to point to your Pihole instance.

Installing Pihole in Docker

For Pihole, you could use Docker CLI or Docker Compose to deploy it successfully. 

If you are using Docker CLI, then: 

1. Pull the official Pihole image using: docker pull pihole/pihole
2. Create and run a container:

docker run -d \

  –name pihole \

  -p 53:53/tcp -p 53:53/udp \

  -p 80:80 \

  -v /etc/pihole:/etc/pihole \

  -v /etc/dnsmasq.d:/etc/dnsmasq.d \

  -e TZ=”Your_Timezone” \

  -e WEBPASSWORD=”strongpassword” \

  –dns=127.0.0.1 –dns=1.1.1.1 \

  –restart=unless-stopped \

  pihole/pihole

3. Once running, access Pihole’s web interface at:
   http://<your-server-ip>/admin

If you are using Docker Compose, then: 

1. Create a file named docker-compose.yml:
   version: “3”

services:

  pihole:

    container_name: pihole

    image: pihole/pihole:latest

    environment:

      TZ: ‘Your_Timezone’

      WEBPASSWORD: ‘strongpassword’

    volumes:

      – ./etc-pihole:/etc/pihole

      – ./etc-dnsmasq.d:/etc/dnsmasq.d

    ports:

      – “53:53/tcp”

      – “53:53/udp”

      – “80:80”

    restart: unless-stopped

2. Start the container:
   docker compose up -d
3. Open the Pihole dashboard at http://<your-server-ip>/admin.

Pihole Docker Configuration Explained

After deploying Pihole in Docker, it is important to properly configure the system to leverage its full potential. Docker enables you to manage Pihole settings, data persistence, and networking easily using EV and Volume mappings. 

1. Environment Variables

Pihole Docker supports several environment variables that control its behavior. Common ones are: 

Variable	Description	Example
TZ	Sets the timezone inside the container	TZ=”Asia/Dubai”
WEBPASSWORD	Defines the admin password for the Pihole dashboard	WEBPASSWORD=”mypassword”
DNS1, DNS2	Upstream DNS servers Pihole will use	DNS1=1.1.1.1, DNS2=8.8.8.8
FTLCONF_LOCAL_IPV4	Specifies the container’s IP address for proper DNS routing	FTLCONF_LOCAL_IPV4=192.168.1.10

You can always add these variables to your Docker or Docker Compose configurations to customize the setup. 

2. Volume Mapping

To ensure that Pihole settings and logs persist even after the container restarts, you must map it to the internal directories to host locations. 

Container Path	Host Path	Purpose
/etc/pihole	/path/on/host/pihole	Stores core configuration files
/etc/dnsmasq.d	/path/on/host/dnsmasq.d	Stores DNS rules and settings

This would allow you to back up, edit, or migrate the Pihole data safely. 

3. Network Configuration

Pihole should run in the bridge and host networking mode, depending on the environment requirements: 

• Bridge Mode: Safer and easier for most setups.
• Host Mode: Required if you want Pihole to handle DNS requests from your entire network.

To use host mode with Docker Compose:

network_mode: “host”

Accessing and Managing Pihole Dashboard

Once Pihole Docker is up and running, you can easily manage it through the web interface by following these steps: 

1. Accessing the Dashboard

Go to your browser and log into: 

http://<your-server-ip>/admin

Log in using the password you set with the WEBPASSWORD variable.

2. Dashboard Features

The Pihole admin dashboard allows you to:

• Monitor the DNS queries and blocked domain in real time. 
• Add custom whitelist and blacklist domains. 
• Configure the upstream DNS providers. 
• View performance and system statistics. 
• Manage clients and DHCP settings. 

3. Command-Line Management

You can also manage Pihole directly with the container shell. 

docker exec -it pihole bash

Useful commands include:

pihole -g      # Update gravity list (ad sources)

pihole -up     # Update Pihole

pihole -d      # Generate debug log

Updating and Maintaining Pihole Docker Container

Regular updates and continuous maintenance ensure that your Pihole instance stays secure and efficient. 

1. Updating the Pihole Image

To update Pihole:

docker pull pihole/pihole:latest

docker stop pihole

docker rm pihole

docker compose up -d

Your data is safe if the volumes are mapped correctly. 

2. Checking Logs

Monitor logs to identify issues or performance concerns.

docker logs pihole

For persistent log access, check your mapped folder, such as /etc/pihole/pihole.log).

3. Backup and Restore

Backup the Pihole configurations by copying the volume folders: 

cp -r /path/on/host/pihole /backup/location/

Restore by replacing the same folders before redeploying the container.

4. Restarting the Container

To apply configuration updates or to refresh the service, use: 

docker restart pihole

Common Issues and Fixes

While Pihole Docker runs smoothly for most systems, there are a few common issues that might arise. Here is a small troubleshooting guide to help you identity issues and solve them efficiently: 

Issue	Possible Cause	Fix
Pihole dashboard not loading	Container not running or wrong port mapping	Run docker ps to verify container status; check that ports 80/443 are correctly mapped
DNS not resolving	Network mode misconfiguration	Use network_mode: host or ensure proper bridge configuration
Settings lost after restart	Volumes not mapped correctly	Map /etc/pihole and /etc/dnsmasq.d to persistent host directories
“FTL failed to start” error	Corrupted gravity database	Run pihole -g inside the container to rebuild gravity list
Cannot update Pihole	Old container version or permission issues	Remove the old container and redeploy with the latest image
Dashboard password not accepted	Incorrect WEBPASSWORD variable	Reset password by running docker exec -it pihole pihole -a -p

Conclusion

Running Pihole Docker combines the power of a strong ad-blocker and network protection with the flexibility and portability that comes with Docker containers. By leveraging the combined powers, you can easily manage it with minimal resources and isolate it from the system. 

FAQs