Pi-hole - Self Host Lab

Pi-hole is a DNS sinkhole that blocks ads and trackers for every device on your network at once, not just inside one browser. It intercepts the DNS queries your devices make before loading a page or app, checks each requested domain against blocklists, and refuses to resolve the ones that match. No ad loads, because the device asking for it never gets an address to load it from. Despite the name, Pi-hole doesn’t need a Raspberry Pi: it runs on any always-on Linux box, mini PC, NAS, or Docker host. The Pi’s low power draw is just why the name stuck.

Where Pi-hole came from

Developer Jacob Salmela built Pi-hole in 2014 as an open-source alternative to AdTrap, a commercial ad-blocking appliance, running it on a Raspberry Pi mostly because that was the cheap, always-on hardware he had. Pi-hole 2.0 followed in 2015, and by 2017 the project registered “Pi-hole” as a US trademark under Pi-hole, LLC. It’s still built by a small, mostly volunteer team, funded through donations and GitHub Sponsors.

License: Pi-hole Core is licensed under the EUPL-1.2 (European Union Public License), confirmed directly from the LICENSE file in the pi-hole/pi-hole GitHub repo, not assumed from a badge. EUPL is a copyleft license in the same family as the GPL, which its own text lists as compatible. For a personal, unmodified install, its share-back obligations don’t apply, they only trigger once you distribute the software to others.

Quick facts: Official site pi-hole.net · GitHub pi-hole/pi-hole, 59,800+ stars · Current release v6.4.3 · Docker image pihole/pihole

How the DNS sinkhole actually blocks ads

Every device on your network already asks a DNS server “what’s the IP address for this domain?” before loading anything. Point that lookup at Pi-hole instead of your ISP’s resolver, and its FTLDNS engine, a daemon wrapping a modified dnsmasq, checks each request against your subscribed blocklists before answering. A match gets a dead-end response instead of the real address; anything not on a list gets forwarded to your configured upstream resolver, Cloudflare, Google, Quad9, or your ISP, and cached for next time.

Because this happens at the network level instead of inside a browser, it reaches things a normal ad blocker can’t: smart TVs, game consoles, IoT gadgets. That only works once you actually point devices at Pi-hole, either through your router’s DHCP settings, one change covering the whole network, or manually per device. Pi-hole can also run its own DHCP server if your router won’t expose a DNS override, though that hands it responsibility for IP addresses too, not just domains.

Installing Pi-hole with Docker

Docker is the fastest way to get Pi-hole running, and the project maintains its own image. A minimal compose file:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      TZ: 'Europe/London'
      FTLCONF_webserver_api_password: 'change-this-password'
    volumes:
      - './etc-pihole:/etc/pihole'
    restart: unless-stopped

docker compose up -d

Set TZ to your own time zone and pick a real password, an unset one gets replaced with a random password buried in the container logs. Want DHCP too? Add "67:67/udp" to the ports list and cap_add: NET_ADMIN, per Pi-hole’s Docker documentation.

Prefer bare metal? Pi-hole’s one-line installer (curl -sSL https://install.pi-hole.net | bash) is the official quick path, though the project’s own README admits piping straight to bash is controversial since you can’t read the script first, and documents cloning the repo and running basic-install.sh yourself instead.

Hardware: Pi-hole is genuinely light. The official docs list 512MB RAM and 2GB of free storage as the minimum, 4GB recommended, running on x86_64, ARM (v6 through v8), or RISC-V hardware. A Raspberry Pi Zero 2 W or any Pi 3/4/5 runs it without effort, and it’s just as happy sharing a NAS or mini PC already doing other jobs. No GPU, no database server, no multi-container stack needed. Still picking hardware? Our homelab setup guide for beginners breaks down the trade-offs.

That simplicity is why we rate Pi-hole Easy, not Medium: the base install is one container, and the only real configuration step is pointing your router at it. Where it gets more involved is optional. Taking over DHCP protects every device automatically, but it also makes Pi-hole a single point of failure for handing out IP addresses, not just DNS: a crash means devices can’t get online at all, not just that ads stop being blocked. Wanting zero downtime pushes further, into running a second, synced Pi-hole with something like keepalived and Gravity Sync. Neither is required to get real value on day one, but budget more time if you’re planning either.

Never expose port 53 to the public internet. Pi-hole, like any DNS resolver, is a textbook target for DNS amplification and reflection attacks: an attacker spoofs a victim’s IP address, fires a small query at every open resolver it can find, and each one blasts a much larger response back at the victim instead of the attacker. DNS abuse like this is consistently one of the largest categories of DDoS traffic on the internet, and Pi-hole’s own docs are explicit that it’s “designed to work inside a local network,” with sample firewall rules built to block internet-origin traffic. Keep Pi-hole on your LAN, and reach it over a VPN or a mesh network like Tailscale for remote management instead of forwarding port 53 or 80/443. We make the same point for Vaultwarden and Nextcloud; our Jellyfin remote access guide covers the setup in more detail.

Pi-hole: pros and cons

Blocks ads and trackers for every device on the network at once, including smart TVs, consoles, and IoT gear that can’t run browser extensions
Free and open source under the EUPL-1.2, with a small but active volunteer team behind it
Genuinely lightweight: 512MB RAM and one container gets you real protection
Built-in query log and stats dashboard show exactly what your network is calling out to

Only blocks what DNS can see, so ads served from the same domain as the content itself, some YouTube and in-app ads, get through anyway
A crash or reboot takes DNS down for every device pointed at it, unless you’ve planned a fallback
Real protection depends on your router forwarding DNS correctly, or Pi-hole running DHCP
Doesn’t ship with built-in encrypted DNS; getting DoH or DoT means adding another piece

Alternatives worth knowing about

AdGuard Home is Pi-hole’s closest direct competitor, doing the same core job: DNS-level ad and tracker blocking for a whole network, from a single binary. The practical difference is native DNS-over-HTTPS, DNS-over-TLS, and DNS-over-QUIC support built in, where Pi-hole’s core stays focused on the sinkhole and blocklist job and needs an added piece like cloudflared or unbound (both covered in Pi-hole’s own guides) for encrypted upstream DNS. Both can optionally run DHCP. AdGuard Home gets the full treatment in its own review, not a comparison table here.

NextDNS runs the same idea as a cloud service, no hardware required. Technitium DNS Server is another self-hosted option picking up a following among people who want more direct DNS-server control, since it runs a full recursive resolver instead of just forwarding filtered queries.

For more homelab security tooling, browse our Network & Security archive.

FAQ

Does Pi-hole block all ads?

No. It only blocks what it can see and resolve at the DNS level, so ads served from the same domain as the content itself, some YouTube and in-app ads being the classic example, still get through: blocking that domain would break the app entirely. A browser-based blocker like uBlock Origin still earns its place alongside Pi-hole for that last mile.

Is Pi-hole legal to use?

Yes. It’s DNS-level filtering software running on hardware you own, functionally similar to editing a hosts file or using any other ad blocker, just applied network-wide.