What Pi-hole Does

Pi-hole is a DNS sinkhole. It sits between your network and the internet, intercepts every DNS query your devices make, and returns a null response for domains on its blocklists — advertising networks, tracking pixels, telemetry endpoints, and optionally adult content domains.

The filtering happens at the DNS level. No browser extension to install. No per-device configuration. Every device on the network — phones, tablets, smart TVs, game consoles, IoT devices, guest devices — benefits the moment you point your router's DNS at the Pi-hole. When a device asks "where is doubleclick.net?", Pi-hole answers with nothing. The ad request never leaves your network. The page loads faster because it is not waiting for tracking scripts to phone home, render invisible pixels, or fingerprint the browser.

This matters beyond convenience. Advertising networks are surveillance infrastructure. They track which sites you visit, what you search for, what you buy, and where you are. They build profiles that follow you across devices, across sites, and across years. Pi-hole does not eliminate all of this — nothing does — but it blocks the DNS-level component for every device on your network, including the ones that cannot run browser extensions.

Hardware and Install Options

The original use case is a Raspberry Pi — a £35 single-board computer running headless on your network. A Pi Zero W is sufficient. Any spare machine running Ubuntu, Debian, Fedora, or Raspberry Pi OS works equally well. A virtual machine on an existing server is fine. A Docker container works if you already run Docker. This tutorial covers the bare-metal install on Ubuntu or Raspberry Pi OS, because that is the simplest path with the fewest moving parts.

Give the machine a static IP address before you start. DHCP-assigned addresses shift when leases expire or when the router restarts, and when your DNS server's address changes, every device on the network loses name resolution. Nothing works. Set the static IP in your router's DHCP reservation table — find the machine's MAC address and assign it a fixed IP — or configure a static address directly in the machine's network settings. Either method works. The router reservation is easier to manage because it lives in one place.

The machine needs to be on whenever the network is in use. If the Pi-hole is powered off, DNS resolution stops for every device pointed at it. A Raspberry Pi draws about 3 watts, costs roughly £5 a year in electricity, and runs silently. Leave it on.

Installation

Run the installer:

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

This downloads the Pi-hole installer script and runs it interactively. It checks dependencies, installs them if missing, configures the DNS resolver, sets up the web interface, and walks you through several prompts. The entire process takes about five minutes on a fresh system.

The important choices during installation:

Upstream DNS provider — the resolver Pi-hole forwards non-blocked queries to. When a device asks for a domain that is not on any blocklist, Pi-hole passes the query to this upstream resolver. Choose Cloudflare (1.1.1.1) or Quad9 (9.9.9.9). Cloudflare is fast and has a clear privacy policy — they do not sell query data and purge logs within 24 hours. Quad9 blocks known malware domains at the resolver level, adding another layer of protection. Do not choose Google. Google is an advertising company. Its DNS service exists to gather data about which domains the world resolves, and that data feeds the same advertising infrastructure Pi-hole exists to block.

Install the web admin interface — yes. The dashboard is how you monitor queries, manage blocklists, and whitelist domains. There is no good reason to skip it.

Log queries — yes. The query log is essential for troubleshooting. When Pi-hole blocks something you need, the log tells you which domain was blocked and when. Without it, you are guessing.

The installer sets a random admin password and displays it at the end of the process. Write it down. Change it afterwards with pihole -a -p if you want something memorable.

Router Configuration

Set your router's DNS server to the Pi-hole's IP address. Every device on the network will then use Pi-hole automatically — no per-device configuration needed, no software to install, no profiles to push.

Most routers expose this in one of two places. Check the DHCP settings first — look for a "DNS server" or "DNS 1" field in the DHCP configuration section. When a device joins the network and requests an IP via DHCP, the router tells it which DNS server to use. Set this to the Pi-hole's IP.

If your router does not have that option, check the WAN or internet settings for a DNS override. This changes the DNS server for the router itself, and some routers propagate this to clients.

Some ISP-supplied routers — particularly those from BT, Virgin Media, and Sky — do not allow custom DNS settings at all. The option is either missing or greyed out. In that case, you have three choices: replace the router with one you control, set each device's DNS manually, or run Pi-hole as a DHCP server instead of the router. Setting each device manually works but defeats the purpose for new devices and guests — they bypass Pi-hole unless individually configured. Running Pi-hole as the DHCP server is a cleaner solution but adds complexity.

The Web Dashboard

Access the dashboard at http://pi.hole/admin or http://<your-pihole-ip>/admin. Log in with the admin password from the installation.

The dashboard shows total queries, queries blocked, the blocking percentage, and the top blocked domains. A typical home network blocks between 15% and 40% of all DNS queries — that figure is how much tracking and advertising is embedded in normal internet use. The first time you see it, it is sobering.

The query log shows every DNS request from every device on your network in real time. You can filter by client, by domain, by status — blocked or allowed. You can see exactly what your smart TV is phoning home to at three in the morning, which apps are making background requests every thirty seconds, and which domains are being blocked most frequently.

The long-term data page shows trends over days and weeks. It is useful for spotting anomalies — a device suddenly making thousands of queries to an unfamiliar domain warrants investigation. It might be a compromised device, a misconfigured app, or malware phoning home to a command-and-control server. Pi-hole does not just block ads — it makes your network's DNS traffic visible.

Blocklist Configuration

The default blocklist — Steven Black's unified hosts list — covers mainstream advertising and tracking domains. It is a reasonable starting point but not comprehensive. Tens of thousands of domains are on it. Millions more exist.

Add additional lists for broader coverage:

Add lists in the web interface under Group Management → Adlists. Paste the list URL — each list is a plain text file hosted online, one domain per line — and save. After adding all your lists, pull and merge them:

pihole -g

This runs gravity — Pi-hole's list processing engine. It downloads every configured list, deduplicates the entries, removes comments and formatting, and compiles them into a single blocking database. Gravity typically takes under a minute, even with hundreds of thousands of domains across multiple lists. Run gravity after every list change and periodically — weekly is reasonable — to pick up updates to the upstream lists themselves. List maintainers add new tracking domains and remove false positives continuously.

Do not add every list you find. More lists means more false positives — legitimate domains incorrectly flagged as trackers. Start with the default list and one aggregated list like OISD. Add specific-purpose lists — adult content, malware, social media — only when you need them. A targeted configuration with a few well-maintained lists is more useful than a sprawling one that blocks half the internet and requires constant whitelisting.

Whitelisting

Pi-hole will break things. Accept this upfront. The question is not whether it will happen but how quickly you identify and fix it.

Streaming services, software update mechanisms, authentication flows, and CDN-hosted resources sometimes share domains with tracking infrastructure. A domain that serves both the login page and the tracking pixel cannot be blocked without blocking the login. When something stops working — a page fails to load, a login flow hangs, a video will not play, an app reports a network error — check the query log first.

Filter the log by the time the problem occurred and the device it occurred on. Look for blocked domains that correspond to the failure. The domain name usually makes the connection obvious — auth.example.com blocked at the same moment the login failed is not a coincidence.

Whitelist the domain in the web interface or from the command line:

pihole -w example.com

The regex whitelist handles patterns. If a service uses rotating subdomains — cdn1.example.com, cdn2.example.com, and so on — a single regex entry is cleaner than a dozen individual entries. The web interface supports both exact-match and regex whitelisting.

Keep a note of what you whitelist and why. Over time, you build a stable configuration that blocks what you want blocked and allows what you need. The first week requires the most whitelisting. After that, adjustments are rare.

The Gotchas

HTTPS and Same-Domain Ads

Pi-hole blocks by domain name, not by content. If advertisements are served from the same domain as the content — YouTube is the most prominent example — Pi-hole cannot distinguish the ad request from the content request. Both resolve to the same domain. Blocking that domain blocks the ads and the content. There is no fix for this at the DNS level. YouTube serves ads from googlevideo.com, the same domain that serves the video stream itself. This is deliberate — it makes DNS-level ad blocking impossible for YouTube specifically.

For YouTube ads, a browser-based blocker like uBlock Origin is the only effective tool. Pi-hole and uBlock Origin complement each other — Pi-hole handles network-wide DNS-level blocking, uBlock Origin handles same-domain and in-page content filtering.

Hard-Coded DNS

Some devices bypass your router's DNS settings entirely. Google Home devices, Chromecast, certain Samsung and LG smart TVs, and various IoT hardware have DNS resolvers like 8.8.8.8 hard-coded into their firmware. These devices ignore Pi-hole regardless of your router configuration. They send DNS queries directly to Google's resolver, bypassing your network's DNS entirely.

Fix this with a firewall rule that intercepts all outbound DNS traffic and redirects it to Pi-hole:

iptables -t nat -A PREROUTING -p udp --dport 53 -j DNAT --to-destination <pihole_ip>:53
iptables -t nat -A PREROUTING -p tcp --dport 53 -j DNAT --to-destination <pihole_ip>:53

Run these on the Pi-hole machine itself or on your router if it supports custom firewall rules. The rules intercept any DNS query leaving your network — regardless of the destination the device intended — and redirect it to Pi-hole. Add the rules to your startup configuration so they persist across reboots. On Ubuntu, use iptables-persistent. On a router running OpenWrt, add them to the firewall configuration.

You also need to exclude the Pi-hole itself from these rules, or its upstream queries to Cloudflare or Quad9 will loop back to itself. Add an exemption rule before the redirect rules for traffic originating from the Pi-hole's IP address.

DNS-over-HTTPS in Browsers

Firefox and Chrome can use DNS-over-HTTPS — encrypting DNS queries and sending them directly to a resolver like Cloudflare or Google, bypassing Pi-hole entirely. This is enabled by default in some browser configurations and some regions.

Disable DoH in the browser settings on each device. Alternatively, Pi-hole can block the canary domain use-application-dns.net, which tells Firefox not to enable DoH automatically — add this domain to your blocklist. For a more thorough approach, block the IP addresses of known DoH resolvers at the firewall level, though this requires maintaining a list of IPs.

Captive Portals

Hotel and café Wi-Fi login pages — captive portals — rely on DNS to redirect you to the login page. If your mobile device is configured to use your home Pi-hole as its DNS server while you are on a different network, the captive portal cannot redirect you and the login page never appears.

Configure Pi-hole as the DNS server only for your home network. On mobile devices, set DNS per network — use Pi-hole on your home Wi-Fi and the default DNS on other networks. Do not set Pi-hole as a system-wide DNS override on devices that leave your home.

Group Management

Pi-hole supports client groups with different blocklist assignments. This is configured in the web interface under Group Management — one of Pi-hole's most useful features for households with mixed requirements.

Create groups for different device categories. Children's devices get stricter filtering — adult content lists, social media domain lists, gaming platform trackers, time-wasting sites. Work devices get the standard advertising and tracking lists. Guest devices get the baseline list plus malware domain lists. Your own devices get whatever configuration you prefer.

Assign clients to groups by IP address or MAC address. Assign adlists to groups. A client inherits the blocklists of every group it belongs to. A device can belong to multiple groups. This is flexible enough to handle most household configurations without complexity.

The default group applies to any client that has not been explicitly assigned elsewhere. New devices joining the network — a guest's phone, a new tablet — get the default group's filtering automatically. Set the default group to a reasonable baseline, then create stricter groups for children's devices and looser groups for devices you trust.

Groups also apply to individual domains — you can whitelist a domain for one group without whitelisting it for all. A streaming service domain that adults need can be allowed for the adult group while remaining blocked for children. This granularity is powerful for households with different age groups and different requirements.

Backup and Recovery

Pi-hole includes a built-in backup mechanism through the web interface — Settings → Teleporter. Export creates a compressed archive of your configuration: blocklists, whitelists, blacklists, group assignments, DNS settings, and client mappings. Import restores it. Take a Teleporter backup before upgrading Pi-hole, before making significant configuration changes, and periodically as insurance.

If you are running Pi-hole on a Raspberry Pi with an SD card, the card will eventually fail. SD cards have a limited number of write cycles, and Pi-hole writes to the query log continuously. This is not a question of whether but when. Keep a Teleporter backup somewhere other than the Pi-hole itself — on another machine, in cloud storage, anywhere that survives the SD card dying. When the card fails — and you will know because DNS resolution stops — flash a new card, reinstall Pi-hole, import the Teleporter backup, and you are running again within fifteen minutes.

Maintenance

Update Pi-hole itself:

pihole -up

Refresh blocklists by running gravity:

pihole -g

View the console dashboard:

pihole -c

Log rotation is handled automatically. Storage requirements are modest — a Raspberry Pi's SD card has more than enough space for years of query logs at default retention settings.

Check the dashboard weekly. Look for unusual spikes in blocked queries, new domains appearing in the top blocked or top permitted lists, and devices making unexpected numbers of requests. A smart TV making ten thousand queries a day to telemetry domains is normal — depressing, but normal. A device making ten thousand queries to a domain you do not recognise is not.

Performance

Pi-hole handles tens of thousands of queries per second on a Raspberry Pi. It is not a bottleneck for any home network. DNS resolution is often faster than your ISP's default resolver because frequently queried domains are cached locally — the answer comes from your Pi-hole's cache in under a millisecond, not from a server on the other side of the country.

The memory footprint is small. The CPU usage is negligible. A Raspberry Pi running Pi-hole can run other lightweight services simultaneously without issue.

The home network tutorial elsewhere on this site covers Pi-hole briefly as one filtering option. This tutorial is the full walkthrough.

Set up a machine with a static IP, run the installer, point your router's DNS at it, add the blocklists that match your household's needs, configure firewall rules to catch hard-coded DNS, and check the dashboard weekly. The initial setup takes thirty minutes. The ongoing maintenance takes five minutes a week. The reduction in tracking, advertising, and unwanted network traffic is immediate, measurable, and — once you see the dashboard numbers — difficult to live without.