Set Up Pi-hole on Raspberry Pi: Network-Wide Ad and DNS Blocking

Network advertising has evolved from simple image banners into pervasive tracking scripts, fingerprinting libraries, and telemetry beacons embedded inside websites, smart TVs, and mobile apps. Rather than installing resource-heavy browser extensions on every household phone, tablet, laptop, and media streamer, Pi-hole operates at the network domain layer. By functioning as your local DNS (Domain Name System) sinkhole, Pi-hole intercepts domain resolution queries and returns a null address before a connection to an ad or tracker can ever be established.

Running Pi-hole on a Raspberry Pi gives your entire household faster page load times, reduced mobile data waste, and network-wide privacy. This guide covers hardware selection, choosing between bare-metal and Docker Compose deployments, configuring upstream DNS with recursive resolution, curating blocklists without breaking legitimate streaming apps, setting up local network DNS records, and configuring router DHCP.

Hardware planning and network placement

DNS is the foundation of network operations. If your DNS resolver goes offline, computers and phones will report that the internet is disconnected, even though physical network links remain active.

• Board Selection: Pi-hole has remarkably modest hardware requirements. It runs comfortably on a Raspberry Pi Zero 2 W, Raspberry Pi 3, Raspberry Pi 4, or Raspberry Pi 5 with as little as 512 MB of RAM.
• Ethernet vs Wi-Fi: While a Pi Zero 2 W on Wi-Fi works for light home use, a wired gigabit Ethernet connection (on a Pi 3B+, 4, or 5) is strongly recommended for primary household resolvers to eliminate wireless latency jitter and packet drop.
• Power and Storage: Use a stable 5V power supply and a high-endurance microSD card. Pi-hole writes frequent query logs to an internal SQLite long-term database (/etc/pihole/pihole-FTL.db).
• Static IP Configuration: The Raspberry Pi hosting Pi-hole must possess an immutable, static IP address on your local subnet so your router and clients never lose their assigned DNS endpoint.

Assign a static IP using NetworkManager (nmcli) on modern Raspberry Pi OS:

nmcli connection show
sudo nmcli connection modify "Wired connection 1" ipv4.addresses 192.168.1.50/24 ipv4.gateway 192.168.1.1 ipv4.dns "1.1.1.1,1.0.0.1" ipv4.method manual
sudo nmcli connection up "Wired connection 1"

Architecture choice: Bare-Metal vs Docker Compose

Pi-hole can be installed directly onto Raspberry Pi OS using the automated installation script, or isolated inside a Docker container using Docker Compose.

For a single-purpose Pi, bare-metal is simple and native. If you run multiple homelab services (such as Open Pi, Vaultwarden, or Portainer), Docker Compose is the cleaner architecture.

Method 1: Bare-Metal Installation

Update your operating system package repositories and retrieve the official Pi-hole installation script:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl
curl -fsSL https://install.pi-hole.net -o pihole-install.sh
less pihole-install.sh
sudo bash pihole-install.sh

During the interactive terminal wizard: 1. Confirm the static IP address assigned to your Ethernet interface (eth0). 2. Choose an upstream DNS provider (such as Cloudflare 1.1.1.1 or Quad9 9.9.9.9 with malware blocking). 3. Confirm installation of the default StevenBlack unified hosts blocklist. 4. Enable the admin web interface and the automated query log. 5. Record the temporary web administrator password printed at the conclusion of the installation script.

Change the administrator password to a secure passphrase at any time:

sudo pihole -a -p

Method 2: Docker Compose Deployment

If you prefer containerized management, create a dedicated project directory:

mkdir -p "$HOME/pihole/etc-pihole" "$HOME/pihole/etc-dnsmasq.d"
cd "$HOME/pihole"

Create a compose.yaml file:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80/tcp"
    environment:
      TZ: 'UTC'
      WEBPASSWORD: 'your_strong_admin_password'
      PIHOLE_DNS_: '1.1.1.1;1.0.0.1'
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    restart: unless-stopped

Launch the container and monitor its startup logs:

docker compose up -d
docker compose logs -f

Access the admin dashboard at http://<YOUR_PI_IP>:8080/admin/.

Upstream DNS options: Cloudflare, Quad9, or Unbound Recursive Resolver

Pi-hole filters queries, but when a client requests an unblocked domain (like example.com), Pi-hole forwards that query to an upstream resolver.

Upstream DNS options:

• Cloudflare (1.1.1.1, 1.0.0.1): Emphasizes speed and strict privacy audits.
• Quad9 (9.9.9.9): Automatically blocks malicious phishing and malware domains at the upstream level.
• Unbound (Recursive DNS Resolver): Instead of sending your queries to third-party companies, you can run Unbound directly on your Raspberry Pi. Unbound queries root DNS servers directly (a.root-servers.net down to authoritative TLD nameservers), giving you true end-to-end DNS sovereignty without intermediaries.

Testing DNS filtering on a single client

Never switch your whole network to a newly deployed DNS server without verifying it on a single machine first.

From your workstation terminal, use dig or nslookup to test domain resolution directly against the Pi-hole IP:

dig @192.168.1.50 example.com +short
dig @192.168.1.50 fls-na.amazon.com +short

The first command should return the legitimate IP address of example.com. The second query (a known tracking domain) should return 0.0.0.0, proving that Pi-hole's DNS sinkhole successfully blocked the query.

Open http://192.168.1.50/admin/, log in, and verify that the query appears in the Query Log with status Blocked (gravity).

Router configuration: DHCP distribution vs WAN DNS

To enable ad blocking for every device automatically, configure your router to hand out your Pi-hole's IP address as the local DNS server.

Recommended approach: LAN DHCP DNS

Log in to your home router admin settings and navigate to LAN or DHCP Server Settings. In the DNS Server 1 field, enter your Raspberry Pi's static IP address (192.168.1.50). Leave DNS Server 2 and 3 blank.

Important warning: Do not enter a public DNS server (such as 8.8.8.8) as a "secondary" DNS in your router. Most operating systems treat primary and secondary DNS servers interchangeably; if a secondary is listed, devices will route a substantial portion of queries around Pi-hole, bypassing ad blocking entirely.

What if your ISP router locks DNS settings?

If your ISP-supplied router does not allow editing DHCP DNS settings: 1. Disable the DHCP server entirely in your router settings. 2. Open Pi-hole's admin interface, navigate to Settings -> DHCP, and enable DHCP server on Pi-hole. 3. Set your local IP range (e.g., 192.168.1.100 to 192.168.1.250) and gateway (192.168.1.1). Pi-hole will handle IP assignment and DNS configuration for all network clients.

Adlist curation and whitelist management

Pi-hole pulls domain lists into a local SQLite compiled index called Gravity.

Curating blocklists

Navigate to Adlists in the admin sidebar. While it is tempting to add millions of domains from random internet repositories, aggressive lists frequently break banking portals, flight search engines, and streaming applications.

Stick to well-maintained, curated lists such as the Firebog Non-crossed Lists (the "Tick lists"). After adding new URLs, recompile the Gravity database:

pihole -g

Whitelisting common services

Certain smart TVs and streaming services require telemetry endpoints to function. If Netflix or Disney+ fails to load video profiles, inspect the Query Log, locate the blocked query from that TV's IP, and click Whitelist. You can also add common regex rules for streaming services without opening tracking across other devices.

Local DNS records for your homelab

Instead of memorizing IP addresses and port numbers for all your Raspberry Pi services, use Pi-hole's built-in Local DNS Records: 1. In the admin interface, navigate to Local DNS -> DNS Records. 2. Map local domain names to your internal IP addresses: - home.lan -> 192.168.1.50 - nas.lan -> 192.168.1.55 - assistant.lan -> 192.168.1.60 3. Now, any device on your Wi-Fi or Ethernet network can reach your internal services using clean, memorable names.

Monitor Pi-hole with Open Pi

Pi-hole is an always-on infrastructure service. If the pihole-FTL daemon stops or the Raspberry Pi suffers memory exhaustion, your entire home network loses internet name resolution.

Using the Open Pi mobile app on iOS and Android: - System Resource Metrics: Track CPU load, RAM usage, and core temperature to ensure your Pi-hole board remains healthy. - Service Monitoring: Verify that DNS (port 53) and HTTP services remain active without opening a terminal. - Container Health: For Docker Compose installations, inspect container uptime and restart logs in real time.

Troubleshooting common DNS issues

When network clients experience connection drops or bypass ad filtering:

• Clients Bypassing Pi-hole via IPv6: Many modern routers automatically hand out an IPv6 DNS address alongside IPv4. If clients still see ads, check your router's IPv6 configuration and set the IPv6 DNS to Pi-hole's link-local IPv6 address, or temporarily disable IPv6 DHCP stateful mode.
• Browser Secure DNS (DoH) Bypass: Modern browsers (Chrome, Edge, Firefox) sometimes enable "Secure DNS" (DNS-over-HTTPS) by default, routing queries over encrypted port 443 to Google or Cloudflare. In browser settings, set Secure DNS to "Use current provider" or disable it so queries resolve through the local network.
• Temporary Emergency Disable: If an essential online service is broken and you need immediate household access, click Disable -> For 5 minutes in the Pi-hole sidebar. This temporarily allows all queries without altering your network settings.

Sources and further reading

• Pi-hole: Official Prerequisites and Ports Documentation
• Pi-hole: Docker Official Deployment Guide
• Firebog: Curated and Tested Adlists
• Pi-hole: Configuring Upstream Unbound Recursive Resolver

Monitor your Raspberry Pi from your phone

Check real-time CPU, RAM, temperature, and service health for your networking projects with Open Pi for iOS and Android. Local-first, private, and no cloud account required.

Explore Open Pi ↗App StoreGoogle Play