Raspberry Pi Pi-hole: Complete Setup and Configuration Guide

Raspberry Pi Pi-hole turns a Pi into a DNS sinkhole that blocks ads, trackers, and malware domains for every device on the network. No browser extension, no per-device configuration. Pi-hole intercepts DNS queries, checks them against blocklists, and returns a dead IP for blocked domains while forwarding all other queries to an upstream resolver. This guide covers the complete Bookworm install with nmcli static IP, DNS and blocklist configuration, router setup, group-based per-device filtering, and maintenance commands. For a comparison of Pi-hole versus AdGuard Home, see AdGuard Home vs Pi-hole on Raspberry Pi: Performance Tests and a Real Verdict. For adding Unbound recursive DNS behind Pi-hole, see Unbound Raspberry Pi: Complete Recursive DNS and Pi-hole Setup Guide.

Last tested: Raspberry Pi OS Bookworm Lite 64-bit | May 2026 | Raspberry Pi 4 Model B (2GB) | Pi-hole v5.18, FTL v5.25

Installing Raspberry Pi Pi-hole on Bookworm

Flash Raspberry Pi OS Bookworm Lite 64-bit to a microSD card using Raspberry Pi Imager. Configure hostname (pihole), username, SSH with public key, and Ethernet connection in Imager’s advanced settings. Boot and SSH in.

Set a static IP before installing Pi-hole. Find the current connection name and gateway:

nmcli connection show
ip route | grep default

Set the static IP (replace values with your network details):

sudo nmcli con mod "Wired connection 1" \
  ipv4.addresses "192.168.1.53/24" \
  ipv4.gateway "192.168.1.1" \
  ipv4.dns "127.0.0.1" \
  ipv4.method manual
sudo nmcli con up "Wired connection 1"

The DNS is set to 127.0.0.1 so the Pi itself uses Pi-hole after install. Verify the IP:

hostname -I

Update and install Pi-hole with the official install script:

sudo apt update && sudo apt full-upgrade -y
curl -sSL https://install.pi-hole.net | bash

The installer runs an interactive setup wizard. Accept the static IP it detects. Choose an upstream DNS provider (Cloudflare 1.1.1.1 is fine as a starting point. It can be changed later to Unbound for full recursive resolution). Accept the default blocklist. Enable the web admin interface. Enable logging.

Expected result: The installer completes and prints the Pi-hole admin URL and web password. Access the dashboard at http://192.168.1.53/admin (or the IP you set). Log in with the printed password. Change the password immediately: pihole -a -p. If the dashboard does not load, confirm the Pi-hole service is running: pihole status.

Configuring Raspberry Pi Pi-hole: DNS, Blocklists, and Groups

Upstream DNS. Pi-hole forwards non-blocked queries to an upstream resolver. The default Cloudflare (1.1.1.1) and Google (8.8.8.8) options forward all your DNS queries in plaintext to a third party. For better privacy, configure Unbound as the upstream recursive resolver instead. Unbound resolves queries directly from root servers with no third party involved. See Unbound Raspberry Pi: Complete Recursive DNS and Pi-hole Setup Guide for the full setup. Set upstream DNS in the dashboard under Settings > DNS.

Blocklists. Pi-hole ships with the default StevenBlack Unified Hosts list (~220,000 domains). The dashboard shows the number of blocked domains after gravity update. Common additional lists that add meaningful coverage without excessive false positives:

List name	Domains	Focus	URL
StevenBlack Unified (default)	~220k	Ads + malware	Included in install
OISD Full	~260k	Ads + tracking	https://oisd.nl/full
HaGeZi Personal	~100k	Low false-positive	https://hagezi.pages.dev
1Hosts Lite	~60k	Conservative, fast	https://badmojr.gitlab.io/1hosts/Lite/adblock.txt

Add lists in the dashboard under Group Management > Adlists. After adding new lists, update gravity to download and compile them:

pihole -g

Expected result: Gravity update completes with a count of blocked domains. The dashboard’s total blocked domain count increases. If gravity fails with a network error, check that the Pi has internet access: ping -c 3 1.1.1.1.

Groups and per-device filtering. Pi-hole v5 introduced groups, which let you assign different blocklist combinations to different devices. Useful for: stricter filtering on a child’s device, no filtering on a work laptop, standard filtering for everything else. Create groups under Group Management > Groups. Assign clients (by MAC or IP) to groups under Group Management > Clients. Assign adlists to groups under Group Management > Adlists. The Default group applies to all unassigned clients.

Whitelisting. When a legitimate site or service breaks after Pi-hole is installed, it is usually because a required domain is on a blocklist. Find the blocked domain in the Query Log (click on a blocked entry to see details), then add it to the whitelist: Dashboard > Whitelist, or from the command line:

pihole -w example.com

Router Setup for Network-wide Raspberry Pi Pi-hole Blocking

Pi-hole only blocks ads for devices that use it as their DNS server. There are two ways to route all network traffic through Pi-hole: configure the router’s DHCP server to hand out the Pi’s IP as the DNS server (preferred), or configure each device individually.

Log into the router admin panel (typically at http://192.168.1.1). Navigate to the DHCP settings. Set the primary DNS server to the Pi’s static IP (e.g., 192.168.1.53). Set the secondary DNS to a fallback: either the router’s own IP or a public DNS like 1.1.1.1. The secondary DNS activates only if Pi-hole is unreachable, providing a fallback at the cost of bypassing Pi-hole’s filtering temporarily.

Save the router setting and force devices to renew their DHCP lease. On most devices, toggling WiFi off and on is sufficient. Verify a device is using Pi-hole:

# From another machine on the network:
nslookup ads.example.com 192.168.1.53

A blocked domain should return 0.0.0.0. An allowed domain returns the real IP. Check the Pi-hole dashboard Query Log. Devices making DNS queries should appear there within a few seconds.

Expected result: The Pi-hole dashboard shows queries from multiple clients. The “Queries blocked” percentage climbs from 0% as devices use Pi-hole. After 24 hours of normal use, a typical home network shows 15-25% of queries blocked. If queries from other devices do not appear in the log, those devices are still using their old DNS. Force a DHCP lease renewal on each device.

Maintaining and Troubleshooting Raspberry Pi Pi-hole

Regular maintenance commands. Pi-hole ships with a CLI for all maintenance tasks:

# Update gravity (blocklists) -- run weekly or set a cron:
pihole -g

# Update Pi-hole itself:
pihole -up

# Check Pi-hole status:
pihole status

# View recent blocked queries:
pihole -t   # tail the query log in real time

# Disable Pi-hole for 5 minutes (for troubleshooting):
pihole disable 5m

# Re-enable:
pihole enable

Schedule gravity updates via cron. Add a weekly update that runs at 2am Sunday:

sudo crontab -e
# Add:
0 2 * * 0 /usr/local/bin/pihole -g >> /var/log/pihole/gravity-update.log 2>&1

Troubleshooting: ads still showing. Check that the device’s DNS is actually using Pi-hole: nslookup google.com on the device should show the Pi’s IP as the server. If it shows a different DNS, the DHCP lease has not renewed. Some devices (iPhones, newer Android) use hardcoded DNS or DNS-over-HTTPS that bypasses Pi-hole entirely. For those devices, block port 853 (DNS-over-TLS) at the router and block 8.8.8.8 and 1.1.1.1 at the firewall to force them through Pi-hole.

Troubleshooting: legitimate sites broken. Open the Pi-hole Query Log and filter for the affected domain. If it shows as blocked, click the entry to see which blocklist matched and whitelist the domain. Common false positives: Microsoft Teams requires teams.microsoft.com and related CDN domains; some smart home apps require their telemetry domains to function.

Troubleshooting: Pi-hole not starting after reboot. Check FTL status: sudo systemctl status pihole-FTL. If it failed, check the log: sudo journalctl -u pihole-FTL -n 50. Port 53 conflicts are a common cause: another DNS service occupying port 53. On Bookworm, systemd-resolved may occupy port 53. Disable it: sudo systemctl disable --now systemd-resolved then restart Pi-hole.

For adding Unbound as a recursive resolver behind Pi-hole (eliminating reliance on Cloudflare or Google as upstream DNS), see Unbound Raspberry Pi: Complete Recursive DNS and Pi-hole Setup Guide. For comparing Pi-hole to AdGuard Home, which includes built-in DoH/DoT without extra configuration, see AdGuard Home vs Pi-hole on Raspberry Pi: Performance Tests and a Real Verdict.

FAQ

What Raspberry Pi model is best for Pi-hole?

Any Pi that can run Raspberry Pi OS Lite works. The Pi Zero 2W at $15 handles a single-household load. Pi-hole is not CPU or RAM intensive for typical home use. A Pi 3B+ or Pi 4 (2GB) is more appropriate for households with many devices, large blocklists, or when running other services alongside Pi-hole. Ethernet is strongly preferred over WiFi for any always-on DNS server. WiFi dropouts cause intermittent DNS failures for the whole network. The Pi 4 is the most common choice because it costs the same as an older Pi 3 used, has Ethernet, and leaves headroom for other services.

How does Pi-hole block ads on every device?

Pi-hole acts as the DNS server for the network. When the router’s DHCP server is configured to hand out the Pi’s IP as the DNS server, every device that connects to the network uses Pi-hole to resolve domain names. Pi-hole checks each domain against its blocklists and returns a dead IP (0.0.0.0) for blocked domains, preventing the browser or app from ever reaching the ad server. Devices that hard-code their own DNS or use DNS-over-HTTPS bypass Pi-hole; those require additional router-level firewall rules to redirect.

Does setting dhcpcd.conf work for Pi-hole static IP on Bookworm?

No. Raspberry Pi OS Bookworm uses NetworkManager, not dhcpcd. The /etc/dhcpcd.conf file has no effect on Bookworm. Static IP must be configured with nmcli (command line) or nmtui (text UI). A router DHCP reservation is also a valid approach: the router always assigns the same IP to the Pi’s MAC address, requiring no Pi-side configuration. See Raspberry Pi Static IP: Router Reservation, nmcli, and nmtui Guide.

Can Pi-hole block ads on smart TVs and streaming devices?

Yes, as long as the device uses the network’s DNS (provided by the router’s DHCP). Smart TVs, Roku, Fire TV, Apple TV, and most streaming devices do not hard-code DNS and will use Pi-hole automatically once the router is configured. Samsung and LG smart TVs in particular are known to send significant telemetry that Pi-hole can block. Some streaming devices (Amazon Fire TV) periodically revert to hard-coded DNS; blocking 8.8.8.8 and 8.8.4.4 at the router forces those devices back through Pi-hole.

Should I use Pi-hole or AdGuard Home on Raspberry Pi?

AdGuard Home for a fresh install in 2026 if built-in DoH/DoT encrypted DNS and per-client rules are priorities. It handles both without additional software. Pi-hole if the setup already exists, if tight Unbound integration with a large community of documentation is important, or if the network is complex with VLANs and custom DNS records (dnsmasq handles this better). Both run fine on a Pi Zero 2W or Pi 4. For a full comparison with performance data, see AdGuard Home vs Pi-hole on Raspberry Pi: Performance Tests and a Real Verdict.

References:

• Pi-hole documentation: docs.pi-hole.net
• Pi-hole GitHub: github.com/pi-hole/pi-hole
• StevenBlack hosts: github.com/StevenBlack/hosts
• OISD blocklist: oisd.nl
• HaGeZi blocklists: hagezi.pages.dev

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (2GB). Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. Pi-hole v5.18, FTL v5.25, May 2026.