Pi-hole Docker Setup 2026: Network-Wide Ad Blocking for Homelabs

Reading time: ~12 minutes
Audience: Beginners who want cleaner browsing and reduced tracking on all home devices
Last tested: Pi-hole FTL v6.0, June 2026

What Is Pi-hole?

Overview

Pi-hole is a DNS sinkhole that blocks advertisements, trackers, and malicious domains at the network level. Instead of installing ad blockers on every browser and device, Pi-hole filters DNS requests for your entire household. Smart TVs, mobile apps, IoT devices, and game consoles all benefit without individual configuration.

Think of it as a “network-wide ad blocker” that runs on a small Linux container and consumes less than 512 MB RAM.

Key Benefits

Prerequisites

Hardware Requirements

Software Requirements

• Docker Engine and Docker Compose plugin
• Access to your router’s admin panel (to change DNS settings)
• A Linux host with a static local IP (e.g., 192.168.1.10)

Network Prerequisites

• Your Pi-hole host needs a static IP address. If your router uses DHCP, reserve the IP by MAC address.
• Port 53 (DNS) must not be in use by another service on the host.

Step 1: Deploy Pi-hole with Docker Compose

Objective

Create a Compose file with persistent storage and the correct network mode.

Step-by-Step Instructions

1. Create a project directory:

mkdir -p ~/pihole && cd ~/pihole

1. Create docker-compose.yml:

version: "3.8"

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:2025.07.0  # Pin version for stability
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"  # Admin UI; change if 80 is taken
    environment:
      - TZ=Europe/Berlin  # Change to your timezone
      - WEBPASSWORD=changeme  # Strong password for admin UI
      - FTLCONF_LOCAL_IPV4=192.168.1.10  # Your host's static IP
    volumes:
      - ./etc-pihole:/etc/pihole
      - ./etc-dnsmasq.d:/etc/dnsmasq.d
    cap_add:
      - NET_ADMIN
    dns:
      - 127.0.0.1
      - 1.1.1.1

Port 80 conflict: If your host already runs a web server on port 80, map Pi-hole to a different host port (e.g., 8081:80).

1. Create data directories:

mkdir -p etc-pihole etc-dnsmasq.d

1. Start Pi-hole:

docker compose up -d

1. Verify it is running:

docker compose logs -f

Look for “Blocking … domains” and “FTL started”.

Step 2: Point Your Router to Pi-hole

Objective

Redirect all DNS traffic on your network through Pi-hole.

Step-by-Step Instructions

Option A: Router DNS (Recommended)

1. Log in to your router’s admin panel (usually 192.168.1.1 or 192.168.0.1).
2. Find the DHCP or LAN settings.
3. Set the Primary DNS to your Pi-hole IP (e.g., 192.168.1.10).
4. Set the Secondary DNS to a public resolver like 1.1.1.1 or leave blank (Pi-hole handles upstream).
5. Save and reboot the router or renew DHCP leases on clients.

Important: If Pi-hole goes down and you set no secondary DNS, devices lose internet access. For redundancy, run a second Pi-hole or use a public DNS as secondary (ads will leak through the secondary, but internet stays up).

Option B: Per-Device DNS

If you cannot change router settings (ISP-locked devices), manually set DNS on each device: - Windows: Network settings → Adapter properties → IPv4 → Preferred DNS: 192.168.1.10 - macOS: System Settings → Network → DNS → Add 192.168.1.10 - Android/iOS: Wi-Fi settings → Advanced → DNS → Add 192.168.1.10

Step 3: Configure Blocklists and Whitelists

Objective

Add aggressive blocklists and fix any broken websites.

Step-by-Step Instructions

1. Open the Pi-hole admin dashboard:

http://your-server-ip:8080/admin

Log in with the WEBPASSWORD you set.

1. Navigate to Group Management → Adlists.

2. Add curated blocklists. Start with these reliable sources:

1. Click Tools → Update Gravity to download and compile the lists.

2. After updating, check the dashboard for “Total queries” and “Queries blocked”.

Whitelisting broken sites:

Some sites break when critical trackers are blocked (e.g., login callbacks, captchas). If a site fails: 1. Open Pi-hole dashboard → Query Log 2. Find the blocked domain (highlighted in red) 3. Click Whitelist next to it 4. Common whitelists: client-s.gateway.messenger.live, app-analytics-v2.snapchat.com

Step 4: Monitoring and Maintenance

Objective

Understand your dashboard and keep Pi-hole updated.

Step-by-Step Instructions

Dashboard Overview:

Updating Pi-hole:

cd ~/pihole
docker compose pull
docker compose up -d

Your blocklists, whitelist, and settings persist in ./etc-pihole.

Updating Gravity (blocklists):

In the web UI: Tools → Update Gravity. Schedule this weekly via cron or the UI’s automatic update option.

Pro Tips

Tip 1: Run Pi-hole in Host Network Mode for IPv6

If your network uses IPv6 extensively, host mode simplifies DNS listening:

    network_mode: host

Remove the ports: block when using host mode.

Tip 2: Use Local DNS Records for Homelab Services

Map local domains to internal IPs so you can access services by name: - Local DNS → DNS Records: - proxmox.lan → 192.168.1.5 - nas.lan → 192.168.1.20

This works across all devices without editing individual /etc/hosts files.

Tip 3: Conditional Forwarding for Reverse DNS

If you run Active Directory or want hostname resolution for local IPs: - Settings → DNS → Conditional Forwarding: - Router IP: 192.168.1.1 - Local domain name: lan

Tip 4: Teleporter Backups

Pi-hole includes a built-in backup/restore tool: - Settings → Teleporter - Export your entire config (lists, whitelist, local DNS, groups) - Store the .tar.gz in your backup system

Troubleshooting Common Issues

“DNS_PROBE_FINISHED_BAD_CONFIG” on Clients

• Pi-hole is not reachable. Verify the container is running: docker compose ps
• Check firewall rules: port 53/udp and 53/tcp must be open
• Ensure the Pi-hole host IP is correct in router DNS settings

YouTube Ads Still Appearing

• YouTube serves ads from the same domains as videos (googlevideo.com). DNS blocking cannot distinguish them.
• For YouTube ads, use a browser extension (uBlock Origin) or a client-side solution like SmartTube on Android TV.

Dashboard Shows 0 Queries

• Your devices are not using Pi-hole as their DNS. Double-check router settings or per-device DNS configuration.
• Restart devices to renew DHCP leases with the new DNS server.

Conclusion

Summary

You now have Pi-hole running in Docker, filtering ads and trackers for every device on your network. Your browsing is faster, your privacy is improved, and your IoT devices are no longer phoning home to tracking domains.

Next Steps

• Pair Pi-hole with Unbound for recursive DNS privacy
• Compare Pi-hole vs AdGuard Home
• Add a secondary Pi-hole for DNS redundancy
• Monitor DNS statistics with Grafana

Affiliate Opportunities

• Raspberry Pi: Pi 4 or Pi 5 kits for dedicated low-power DNS
• Mini PCs: Intel N100 systems for Pi-hole + other Docker stacks
• UPS: APC Back-UPS to keep DNS alive during short outages

Internal Linking Strategy

• what-is → /dns-filtering-homelab for readers exploring DNS strategies
• router → /homelab-networking-basics for network fundamentals
• conclusion → /pihole-unbound-dns for the next logical upgrade

CTA

What percentage of your DNS queries is Pi-hole blocking? Share your block rate and favorite blocklists in the comments!

Subscribe to the WordForge newsletter for weekly homelab privacy and networking guides.