>_ ctrlaltbrian
raspberry-pi beginner 30 min

Raspberry Pi: run Pi-hole to block ads network-wide

Install Pi-hole on a Raspberry Pi and block ads, trackers, and malware domains for every device on your network. The single most useful Pi project.

Code available for: Python
Published Aug 5, 2026

Pi-hole is the project I run on every Pi I own. It is a DNS server that blocks ads, trackers, and malware domains. Every device on your network benefits automatically: phones, tablets, smart TVs, game consoles, even that annoying smart fridge.

You do not install anything on the devices. You just point your router at the Pi and Pi-hole blocks the bad stuff before it ever reaches your devices.

This tutorial covers the install and the one configuration change that makes it work.

What you need

  • Raspberry Pi (any model; the Zero 2 W is fine for a small network)
  • Network access to the Pi

Step 1: set a static IP

Pi-hole works best when the Pi has a static IP. If you set this up in the imager (covered in the headless setup tutorial), you are done. If not, edit /etc/dhcpcd.conf:

interface wlan0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8

(Replace with your interface and network. Use eth0 if you are on ethernet.)

Reboot:

sudo reboot

Step 2: install Pi-hole

The one-liner:

curl -sSL https://install.pi-hole.net | sudo bash

This runs an interactive installer. The defaults are sane. Things to change:

  • Upstream DNS provider: Cloudflare (1.1.1.1) or Quad9 (9.9.9.9) are privacy-friendly picks.
  • Blocklists: the default list is fine. You can add more later.
  • Web admin interface: yes.
  • Lighttpd web server: yes (needed for the admin UI).
  • Logging: yes, but consider turning this off for max performance.

The installer tells you the admin password at the end. Save it.

Step 3: access the admin UI

Open a browser:

http://pi-pihole.local/admin

Or by IP:

http://192.168.1.100/admin

You should see the Pi-hole dashboard: queries today, percent blocked, top blocked domains, etc.

Step 4: point your network at Pi-hole

There are two ways:

Log into your router (usually 192.168.1.1). Find the DNS settings. Change the primary DNS to 192.168.1.100 (your Pi’s static IP). Leave the secondary DNS blank, or set it to a public DNS as a fallback (e.g. 1.1.1.1).

This routes every device on your network through Pi-hole automatically. The only exception is devices that hardcode their DNS (e.g. some smart TVs), but most respect the router’s DNS.

Option B: change individual devices

If your router does not let you change DNS, or you only want to block ads on some devices:

  • macOS: System Settings >> Network >> [interface] >> Details >> DNS
  • Windows: Settings >> Network & internet >> [interface] >> DNS server assignment
  • iOS: Settings >> Wi-Fi >> [network] >> Configure DNS >> Manual
  • Android: Settings >> Network >> [network] >> Advanced >> Private DNS

Set the primary DNS to 192.168.1.100.

Option A is the right call for most people. Set it once and forget it.

Step 5: verify it works

From any device on the network, visit:

https://pi-hole.net

You should see the Pi-hole homepage. Now visit:

http://exampleadsdomain.com

If Pi-hole is blocking correctly, you should get a “blocked” page (or the browser will fail to load, depending on configuration).

Check the admin dashboard: you should see “queries today” going up, and “ads blocked” going up.

Adding more blocklists

The default blocklist blocks about 130,000 domains. You can add more. Some good community lists:

To add a list:

  1. Admin UI >> Group Management >> Adlists
  2. Paste the URL
  3. Click “Add”
  4. Tools >> Update Gravity >> Update

You can also disable a list temporarily without removing it (useful for figuring out which list is breaking a website you care about).

Whitelisting domains that get blocked

The most common whitelist entries:

  • Google ads (for sites that detect adblockers and refuse to show content)
  • Affiliate links
  • Your own domains (don’t block yourself)

To whitelist:

  1. Admin UI >> Whitelist
  2. Add the domain
  3. Click “Add”

Or via CLI:

pihole -w example.com

When a website breaks

The most common cause: a list is blocking a domain the website needs. Two paths:

  1. Identify which list is the culprit: disable each list one at a time and retest the website.
  2. Whitelist the domain temporarily.

For the rare case where the website is unusable without ads (e.g. YouTube with anti-adblock), whitelist or use the browser’s built-in ad blocker for that site.

When Pi-hole breaks the internet entirely

You will see this if Pi-hole goes offline. Devices that use Pi-hole as their DNS will fail to resolve any domain. Fix:

  1. SSH into the Pi. Check pihole status.
  2. If Pi-hole is down but the Pi is up: pihole restartdns.
  3. If the Pi is down: reboot it.

To prevent total internet loss if Pi-hole dies, set the router’s secondary DNS to a public server (e.g. 1.1.1.1). Devices will fall back to that if Pi-hole is unreachable.

Performance

Pi-hole on a Pi Zero handles about 100,000 queries per day without breaking a sweat. The Pi 4 handles 10x that. For a home network, even the Pi Zero is overkill.

The DNS query response time is usually under 5 ms. Most of that is the network round-trip, not Pi-hole.

What to build next

  • Pi-hole with Unbound (recursive DNS, no upstream).
  • Pi-hole with DoH/DoT (encrypted DNS queries).
  • A second Pi-hole on a Pi for redundancy.

The Unbound version is in the book Self-Hosted with Raspberry Pi. The redundancy setup is one of the next tutorials on this site.