Some Raspberry Pi projects spend their lives on a shelf. Pi-hole can do useful work every time a device asks where a website lives. It acts as a DNS resolver with filtering, so selected advertising and tracking domains can be blocked before a connection starts.

It is also a good introduction to home networking: you will learn what DNS does, how your router hands out settings, and why a working Wi-Fi connection does not always mean the internet is usable.

Understand what you are building

DNS translates a name into an address. Pi-hole filters those name lookups; it does not inspect and remove every advertisement inside a page or video. Content served from the same domain as the material you want may be impossible to separate using DNS alone.

Use a supported Raspberry Pi OS release and give the Pi a stable address through a DHCP reservation on your router. Pi-hole has modest requirements, including 512 MB of RAM. Ethernet is a sensible choice for something your other devices will rely on.

Prepare a recovery route

Before changing anything, record your router's current DNS settings. Keep its local management address somewhere accessible without an internet connection. Start with one test computer instead of switching your entire household immediately.

On the Pi, update the package index and install curl if needed. Download the official installer into a file so you can inspect it before execution.

BASH
sudo apt update
sudo apt install curl
curl -fsSL https://install.pi-hole.net -o pihole-install.sh
less pihole-install.sh
# Press q to leave the viewer, then install when ready.
sudo bash pihole-install.sh

Follow the installer prompts for the network interface, upstream DNS provider, and filtering configuration. Store the administrative credentials securely. Read any port-conflict message rather than assuming the web interface will always use the same port.

Test one client first

Open the admin address shown by the installer, typically http://PI_ADDRESS/admin/. Substitute your actual address. Set one computer's DNS server to the Pi, reconnect its network connection, and open several websites you normally use.

On Raspberry Pi OS or Debian, dig is available through dnsutils. This example asks your Pi directly, even if your computer's normal DNS settings are different:

BASH
sudo apt install dnsutils
# Replace this example address with your Pi's reserved address.
dig @192.168.1.50 example.com

Look for a successful response and the matching request in Pi-hole's query log. A populated dashboard is useful evidence; a screenshot of the admin login page only proves that the web server is reachable.

Move filtering to the rest of the network

Once the test device works, configure the router's LAN/DHCP DNS setting to advertise the Pi. Router labels vary, and the WAN DNS field may control a different part of the setup. Renew client leases or reconnect devices so they receive the new setting.

Check IPv6 configuration too. An IPv6 DNS server advertised by the router can give clients another path. Browser secure-DNS settings, VPN clients, and devices with hard-coded resolvers may also behave differently from the rest of the network.

Do not add a public resolver as a “secondary” and assume it will only be used during an outage. Clients may use either resolver. A second independently powered Pi-hole is a more consistent redundancy plan if filtering must remain active.

Troubleshoot without breaking the household

If a site stops working, inspect recent blocked queries and allow only the relevant domain after checking what it is. Avoid disabling the whole system permanently to fix one application. If all name lookups fail, restore the recorded DNS settings while you investigate power, network reachability, and the resolver service.

Keep DNS and the admin interface on your trusted network. For access from outside home, build a private Tailscale connection rather than forwarding DNS ports on the router.

Sources and further reading

About this guide

Researched from the official documentation linked above on September 10, 2026. Setup examples are starting points and have not been hardware-tested by Open Pi. Check your board, OS, and the project’s current instructions before installing.