Pi-hole Setup Guide: Block Ads Network-Wide in Your Homelab

Reading time: ~14 minutes Audience: Homelab and self-hosting enthusiasts

What Is Pi-hole?

Overview

Pi-hole is a network-level advertisement and internet tracker blocking application. It acts as a DNS sinkhole, intercepting DNS queries for known ad-serving domains and returning a null response before the connection ever leaves your network. Unlike browser-based blockers, Pi-hole protects every device on your network — smart TVs, IoT devices, mobile apps, and game consoles — without requiring client-side software.

A Brief History

Pi-hole began in 2015 as a lightweight DNS server for Raspberry Pi. It evolved from a simple shell script into a full-featured web application with a custom FTL (Faster Than Light) DNS engine. Pi-hole v5 introduced the gravity database for blocklist management. Pi-hole v6 (released in 2025) added a modern web interface, REST API, and native Docker support. It remains one of the most popular self-hosted projects in the homelab community.

Why Use Pi-hole in Your Homelab?

Network-Wide Ad Blocking

Pi-hole blocks ads at the DNS level. This means every device on your LAN — including devices that cannot install browser extensions — benefits from ad blocking. Game consoles, smart TVs, and IoT devices are notoriously difficult to secure with client-side tools; Pi-hole handles them transparently.

Improved Privacy and Reduced Tracking

By blocking tracker domains (Google Analytics, Facebook Pixel, Amazon Alexa metrics), Pi-hole reduces the data your devices leak. This is not a replacement for a VPN or Tor, but it is a significant layer in a defense-in-depth privacy strategy.

Faster Page Loads and Lower Bandwidth

Ads and trackers consume bandwidth. By blocking them at the DNS level, pages load faster and use less data. On metered or slow connections (mobile tethering, satellite), this is especially noticeable.

Installation

Prerequisites

• A Linux server or Raspberry Pi (any model with 512 MB RAM)
• Docker and Docker Compose
• A static IP or DHCP reservation for the Pi-hole host
• Port 53 (TCP/UDP) available for DNS
• Port 80/443 for the web interface

Method 1: Docker Compose (Recommended)

version: "3.8"

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    restart: always
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      - TZ=Asia/Singapore
      - WEBPASSWORD=***      - FTLCONF_LOCAL_IPV4=192.168.1.10
    volumes:
      - ./etc-pihole:/etc/pihole
      - ./etc-dnsmasq.d:/etc/dnsmasq.d
    cap_add:
      - NET_ADMIN
    dns:
      - 127.0.0.1
      - 1.1.1.1

Deploy:

docker compose up -d

Access the web interface at http://192.168.1.10/admin. Use the password you set in WEBPASSWORD.

Method 2: Bare Metal Installation

On a Raspberry Pi or Debian server:

# Install Pi-hole
curl -sSL https://install.pi-hole.net | bash

The installer walks you through interface selection, upstream DNS, and blocklist subscriptions. It is beginner-friendly but less portable than Docker.

Basic Setup and Configuration

Step 1: Set Pi-hole as Your DNS Server

After installation, point your router’s DHCP DNS server to Pi-hole’s IP. This ensures every device on your network uses Pi-hole automatically.

If your router does not support custom DNS, configure Pi-hole as your DHCP server:

1. In the Pi-hole web UI, go to Settings → DHCP
2. Enable the DHCP server
3. Set the range (e.g., 192.168.1.100 to 192.168.1.200)
4. Disable DHCP on your router

Step 2: Choose Upstream DNS

Pi-hole does not resolve domains itself; it forwards queries to an upstream DNS provider. Recommended options:

For maximum privacy, run a local Unbound recursive resolver alongside Pi-hole. This eliminates the upstream provider entirely.

Step 3: Subscribe to Blocklists

Pi-hole ships with a default blocklist (StevenBlack). You can add more in Group Management → Adlists:

• https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
• https://mirror1.malwaredomains.com/files/justdomains
• https://sysctl.org/camo/b.txt
• https://someonewhocares.org/hosts/zero/hosts
• https://raw.githubusercontent.com/anudeepND/blacklist/master/adservers.txt

Click Update Gravity after adding lists. Be careful: too many lists slow down DNS and cause false positives.

Step 4: Configure Whitelist and Regex

Some sites break when aggressive blocklists are enabled. Whitelist domains in Whitelist → Add to Whitelist. Use regex for wildcard rules:

# Block all .click TLD
(\.|^)click$

# Block specific subdomains
(\.|^)telemetry\.

Advanced Features

Local DNS Records

Pi-hole can act as a local DNS server for your homelab. Add entries in Local DNS → DNS Records:

192.168.1.10    nas.local
192.168.1.20    plex.local
192.168.1.30    nextcloud.local

This gives you human-friendly names for internal services without running a separate DNS server.

Conditional Forwarding

If you have an Active Directory or corporate domain, use conditional forwarding to send specific domain queries to a different DNS server:

Domain: corp.local
Server: 192.168.1.5

This keeps internal resolution working while still blocking ads on the public internet.

Pi-hole as a Recursive Resolver with Unbound

For a no-third-party DNS setup, install Unbound alongside Pi-hole:

sudo apt install -y unbound

Create /etc/unbound/unbound.conf.d/pi-hole.conf:

server:
    verbosity: 0
    interface: 127.0.0.1
    port: 5335
    do-ip4: yes
    do-ip6: yes
    do-udp: yes
    do-tcp: yes
    harden-glue: yes
    harden-dnssec-stripped: yes
    use-caps-for-id: yes
    edns-buffer-size: 1232
    prefetch: yes
    num-threads: 1
    so-rcvbuf: 1m
    so-sndbuf: 1m
    private-address: 192.168.0.0/16
    private-address: 169.254.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
    private-address: fd00::/8
    private-address: fe80::/10

In Pi-hole, set the upstream DNS to 127.0.0.1#5335 (Custom 1).

Query Logging and Long-Term Data

Pi-hole logs all queries. The Long-Term Data page shows top queried domains, top clients, and blocked query trends. Use this to tune your blocklists or identify misbehaving devices. Privacy Note: disable query logging if you have privacy-sensitive users.

Integrating with Your Homelab

VPN Integration (WireGuard / Tailscale)

If you run a VPN, set the VPN’s DNS to Pi-hole. This blocks ads for mobile devices even when they are off the home network. In WireGuard, set DNS = 192.168.1.10 in the client config. In Tailscale, set a DNS override in the admin panel.

Failover with Keepalived or DNS Redundancy

For a redundant setup, run two Pi-hole instances (e.g., on two Raspberry Pis). Use Keepalived for a floating VIP, or configure your router to hand out both DNS servers. If one fails, clients fall back to the other.

Monitoring with Prometheus

Pi-hole v6 exposes a REST API. Use a Prometheus exporter to scrape statistics:

  pihole-exporter:
    image: ekofr/pihole-exporter:latest
    environment:
      - PIHOLE_HOSTNAME=pihole
      - PIHOLE_API_TOKEN=***    ports:
      - "9617:9617"

Visualize queries, blocked percentage, and top clients in Grafana.

Alternatives to Consider

AdGuard Home

AdGuard Home is a modern DNS sinkhole with a polished UI, HTTPS filtering, and parental controls. It supports DoH/DoT (DNS over HTTPS/TLS) out of the box. See our AdGuard Home vs Pi-hole comparison for a full breakdown.

Technitium DNS

Technitium is a full DNS server (not just a sinkhole) with built-in ad blocking, DNSSEC, and DoH/DoT. It is more powerful but more complex than Pi-hole. Use it if you need authoritative DNS or split-horizon resolution.

NextDNS

NextDNS is a cloud-based DNS filtering service. It offers the same blocking as Pi-hole but requires no hardware. The tradeoff is privacy (your DNS queries go to a third party) and cost (free tier has a query limit). Good for travelers or users who cannot self-host.

Frequently Asked Questions

Does Pi-hole block YouTube ads?

Partially. Pi-hole blocks DNS-level YouTube ad domains, but YouTube increasingly serves ads from the same domains as content. For complete YouTube blocking, combine Pi-hole with a browser extension like uBlock Origin.

Why do some sites break after installing Pi-hole?

Aggressive blocklists sometimes block domains required for functionality (e.g., CDN scripts, analytics required for page rendering). Use the Query Log to identify blocked domains, then whitelist them.

Can I run Pi-hole on a VPS?

Yes, but it only blocks ads for devices using that VPS as their DNS server. For personal use, a VPN + Pi-hole VPS setup is common. For a household, run Pi-hole on your local network.

How do I update Pi-hole?

For Docker: pull the latest image and recreate. For bare metal: run pihole -up.

Conclusion

Summary

Pi-hole is the foundational privacy tool for any homelab. It blocks ads, trackers, and malware at the DNS level, protecting every device on your network without client-side configuration. With Docker, it deploys in minutes. With custom blocklists, local DNS, and Unbound recursion, it becomes a powerful network infrastructure component.

Next Steps

• Deploy Pi-hole and set it as your router’s DNS
• Add curated blocklists and test for false positives
• Install Unbound for recursive, third-party-free DNS
• Monitor query statistics with Grafana

Affiliate Opportunities

• installation: hardware — Raspberry Pi kits, mini PCs for Pi-hole hosting
• integration: tool — VPN services (Mullvad, ProtonVPN) for remote DNS
• alternatives: tool — AdGuard Home or NextDNS subscriptions

Internal Linking Strategy

• installation → setup_guide: Docker Compose for beginners
• integration → related_guide: AdGuard Home vs Pi-hole comparison
• alternatives → comparison: DNS filtering in the homelab

CTA

• [comment] What blocklists do you use with Pi-hole? Share your configuration.
• [newsletter] Get weekly homelab networking and privacy guides.
• [internal_link] Next: learn how to set up AdGuard Home as an alternative