Running Pi-hole on a Raspberry Pi transforms a 35-dollar computer into a network-wide DNS sinkhole that blocks ads, trackers, and malware domains before they ever reach your devices. Every phone, smart TV, laptop, and IoT gadget on your network benefits automatically — no per-device apps or browser extensions needed. This guide walks through a clean installation, router integration, and the common pitfalls that trip people up on their first setup, so you can get from unboxed Pi to working ad blocker in under an hour.
What Pi-hole Actually Does
Pi-hole acts as a recursive or forwarding DNS resolver on your local network. When a device makes a DNS query, Pi-hole intercepts it, checks the requested domain against its blocklists, and either returns a null response (for blocked domains) or forwards the query to an upstream resolver like Cloudflare (1.1.1.1) or Google (8.8.8.8). The result is that ad-serving domains resolve to nothing — the ad never loads, saving bandwidth and protecting privacy.
Unlike browser-level blockers, Pi-hole works at the DNS layer, which means it blocks ads inside mobile apps, smart TVs, and any device that cannot run an extension. It also provides a clean query log dashboard so you can see exactly what every device on your network is trying to reach.
What You Need Before Starting
- Raspberry Pi 3B, 3B+, 4, or Zero 2 W — older models work but are slower to update blocklists
- microSD card — 8 GB minimum, 16 GB recommended (Class 10 or A1 rating)
- Raspberry Pi OS Lite (64-bit, no desktop needed) flashed with Raspberry Pi Imager
- Ethernet connection strongly preferred over Wi-Fi for a DNS server
- Router admin access — you will change the DHCP DNS setting
Step 1: Prepare the Raspberry Pi OS Image
Download Raspberry Pi Imager from raspberrypi.com/software. Select Raspberry Pi OS Lite (64-bit) as the operating system. Before writing, click the gear icon to pre-configure: set a hostname (e.g. pihole), enable SSH, and set your Wi-Fi credentials if you cannot use Ethernet. Write the image, insert the card, and power on the Pi.
SSH into the Pi once it boots. The default user is pi if you did not change it in the imager settings, but Raspberry Pi OS now requires you to set a user in the imager before flashing.
Step 2: Set a Static IP Address on the Pi
A DNS server must have a fixed IP. The cleanest way on modern Raspberry Pi OS is to configure a DHCP reservation on your router (preferred) or set a static IP via NetworkManager on the Pi itself. For a quick static IP using NetworkManager (available in Bookworm OS):
Replace 192.168.1.10 with an address outside your router's DHCP pool. Replace 192.168.1.1 with your actual router gateway. Verify the IP stuck with ip addr show eth0.
Step 3: Install Pi-hole
Pi-hole provides a one-line installer. It is safe to review the script at install.pi-hole.net before running. Run the installer as a normal user — it will sudo when needed:
The installer launches a text-based wizard. Key choices:
- Network interface — choose eth0 (or wlan0 if Wi-Fi only)
- Upstream DNS — Cloudflare (1.1.1.1) is a solid default; avoid your ISP's resolver
- Blocklists — accept the default StevenBlack list to start
- Admin web interface — install it (yes)
- Static IP confirmation — confirm the IP you just set
At the end, the installer displays your web admin URL and a randomly generated password. Copy that password immediately — you will need it to log into the dashboard. You can reset it later with pihole -a -p.
Step 4: Point Your Router's DNS to Pi-hole
This is the step that makes Pi-hole work for every device on your network. Log into your router admin panel and change the DNS server distributed by DHCP to the Pi's static IP. Below are the admin URLs and paths for the most common routers:
TP-Link (Archer series)
Admin URL: tplinkwifi.net or 192.168.0.1
Path: Advanced > Network > DHCP Server > Primary DNS
ASUS Routers
Admin URL: router.asus.com or 192.168.1.1
Path: LAN > DHCP Server > DNS Server 1
Netgear (Nighthawk / Orbi)
Admin URL: routerlogin.net or 192.168.1.1
Path: Advanced > Setup > LAN Setup > Address Reservation + Primary DNS
Linksys
Admin URL: 192.168.1.1 or myrouter.local
Path: Connectivity > Local Network > DHCP Server > Static DNS 1
General rule
Set Primary DNS to your Pi's static IP (e.g. 192.168.1.10). Set Secondary DNS to a real upstream resolver like 1.1.1.1 as a fallback — or leave it blank if you want all DNS to go through Pi-hole with no bypass. Leaving a secondary means devices can bypass Pi-hole when it is down; omitting it means the network loses DNS if the Pi reboots. Choose based on your tolerance for ads vs. downtime.
After saving, force your devices to renew their DHCP lease. On Windows: ipconfig /release then ipconfig /renew. On macOS: turn Wi-Fi off and on. On Android/iOS: forget and rejoin the Wi-Fi network.
Step 5: Verify Pi-hole Is Working
Open a browser and navigate to a site you know serves ads, like a news site. The ads should disappear. Then check the Pi-hole dashboard:
Log in with the password from the installer. The dashboard shows total queries, blocked percentage, and a live query log. You should see your devices' hostnames generating traffic within seconds of loading a page.
For a command-line sanity check, query a known ad domain directly against Pi-hole and against an external resolver to compare:
If the first query returns 0.0.0.0 and the second returns a real IP, Pi-hole is intercepting and blocking correctly.
You can also run a full DNS record inspection using the DNS Lookup tool to check how a domain resolves from outside your network — useful to confirm your Pi-hole is not leaking queries to the public internet.
Adding More Blocklists
The default StevenBlack list covers about 130,000 domains. For broader coverage, add curated lists via the Pi-hole dashboard under Adlists:
- https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts — general ads and malware (default)
- https://blocklistproject.github.io/Lists/ads.txt — additional ad networks
- https://blocklistproject.github.io/Lists/tracking.txt — trackers and analytics
- https://raw.githubusercontent.com/DandelionSprout/adfilt/master/Alternate%20versions%20Anti-Malware%20List/AntiMalwareHosts.txt — malware domains
After adding lists, go to Tools > Update Gravity or run:
This downloads and compiles all lists into Pi-hole's gravity database. Expect it to take 1-3 minutes depending on Pi model and list sizes.
Common Problems and Fixes
Pi-hole is installed but devices still get ads
Check that devices actually received the Pi's IP as their DNS server. On Windows, run ipconfig /all and look at the DNS Servers line. On macOS, check System Settings > Network > Details > DNS. If they still show your ISP's DNS, the router DHCP change did not apply. Renew the DHCP lease manually or reboot the device.
Some sites broken or returning NXDOMAIN
Pi-hole is blocking a domain that a legitimate service depends on. Open the dashboard query log and filter by Blocked. Find the domain causing the breakage and click the whitelist button next to it. Alternatively:
Pi-hole web interface not loading
The lighttpd web server may have crashed. Restart it:
DNS stops working when Pi reboots
Pi-hole starts automatically, but there can be a race between the network coming up and the DNS service starting. Ensure the pihole-FTL service is enabled:
Also consider setting a secondary DNS on your router (like 1.1.1.1) so the network does not go dark during Pi reboots.
Clients bypassing Pi-hole with hardcoded DNS
Devices like Google Home and some Android phones use hardcoded DNS (8.8.8.8) and ignore DHCP settings. To force all DNS through Pi-hole, add a firewall rule on your router that intercepts outbound UDP port 53 and redirects it to the Pi's IP. This is router-specific and requires a router that supports iptables or NAT rules (OpenWRT, pfSense, or some ASUS models with advanced settings).
Keeping Pi-hole Updated
Pi-hole ships a built-in update command. Run it periodically or set up a cron job:
This updates the Pi-hole core, the web interface, and the FTL DNS engine. For blocklist updates, schedule gravity updates weekly via the built-in cron entry Pi-hole creates at /etc/cron.d/pihole. The default schedule already runs gravity updates on Sunday at 1:40 AM — you can edit this file to change the timing.
Also keep the underlying OS updated:
Optional: Add Unbound for Full Recursive DNS
By default, Pi-hole forwards queries to an upstream resolver like Cloudflare. That resolver sees all your DNS traffic. For maximum privacy, install Unbound alongside Pi-hole to resolve DNS recursively from root nameservers, eliminating the upstream resolver entirely:
Create a Pi-hole config file for Unbound at /etc/unbound/unbound.conf.d/pi-hole.conf with the settings from the official Pi-hole documentation (listen on 127.0.0.1 port 5335). Then point Pi-hole's upstream DNS to 127.0.0.1#5335 in the dashboard under Settings > DNS. Your queries now go directly to root servers without any third-party resolver seeing your traffic.
Final Thoughts
Pi-hole on a Raspberry Pi is one of the most practical home network projects available — a weekend afternoon of setup delivers years of faster page loads, less tracking, and a clear view of what every device on your network is doing. The query log alone is eye-opening: most households see 20 to 40 percent of all DNS queries blocked as ads and trackers. Once running, Pi-hole needs minimal maintenance beyond occasional blocklist and OS updates. Start with the defaults, whitelist the handful of domains that break, and gradually tune the blocklists as you get comfortable reading the query log.