Pi-hole

Last reviewed Aug 22, 2026 · 732 words

Pi-hole blocks ads and trackers for every device on your network by answering their DNS queries — one install covers the smart TV, the phones, and the guest laptop with nothing installed on any of them. The software takes ten minutes. What earns Pi-hole its reputation as a first homelab project done right is the operational side: a DNS server that must never move, never conflict, and never make your household's internet mysterious.

The port 53 fight comes first

On most modern Linux hosts, systemd-resolved already occupies port 53, and the Pi-hole container will crash-loop until you take it back:

sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved

Then the container itself:

services:
  pihole:
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80"
    environment:
      - TZ=Etc/UTC
      - FTLCONF_webserver_api_password=change-me
    volumes:
      - ./etc-pihole:/etc/pihole
    restart: unless-stopped

Give the host a static IP before anything else. Every device on your network is about to memorise this address; a DHCP lease change later takes the whole network's DNS down with it.

Point clients at it the right way

You have two options, and the difference matters. Setting your router's DHCP DNS option to hand out the Pi-hole's IP means every client queries Pi-hole directly — you get per-device stats and per-device rules. Setting the router's WAN/upstream DNS instead means the router proxies everything, and your dashboard shows one client: the router. Use the DHCP option if your router allows it; if it doesn't (many ISP boxes lock it), disable the router's DHCP server and let Pi-hole be your DHCP server too — it does the job well precisely because ISP firmware so often doesn't.

Blocklists: more is worse

The default blocklist blocks most of what you care about with near-zero false positives. The classic new-user arc is stacking twenty lists to reach millions of blocked domains, then spending a month diagnosing why price trackers, email links, and the partner's favourite shopping site broke. Blocking percentage is not a score. Start with the defaults, add one or two curated lists at most, and learn the whitelist workflow: check the query log, spot the blocked domain, whitelist it, move on — 30 seconds once you've done it twice. Your household's tolerance for "the internet is weird" is a budget; spend it slowly.

What Pi-hole won't block

DNS blocking cannot touch ads served from the same domain as the content, which means YouTube and Twitch ads survive. Devices with hardcoded DNS (some smart TVs, Chromecasts) bypass you unless you add a firewall rule redirecting all port-53 traffic to the Pi-hole. And browsers using DNS-over-HTTPS tunnel past everything — worth knowing before you conclude it isn't working. For the encrypted-DNS story and how the alternatives handle it, see Pi-hole vs AdGuard Home and the wider DNS guide for self-hosters.

Plan for the day the box is down

When Pi-hole is your DNS and Pi-hole is off, the internet is off — that is how DNS works, and it is the number-one source of family friction. Cheap insurance, pick one: run a second Pi-hole on any other always-on device and keep the two aligned with a community sync tool like Orbital Sync; or hand out a public resolver like 9.9.9.9 as a secondary DNS via DHCP, accepting that some queries leak past blocking. What you should not do is nothing. Also keep the admin UI on the LAN — there is no reason to publish it through a reverse proxy, and the remote access guide covers reaching it over a VPN when away.

What I'd do

Static IP, stub listener disabled, the compose file above, DHCP-level DNS, default blocklists plus one curated list, and a second instance on whatever else is always on. Resist the mega-list urge for a month. Run this way, Pi-hole is the rare self-hosted service whose absence — no ads on the TV, faster page loads, a query log that teaches you what your devices phone home to — is noticed within the first hour.