1. What Pi-hole Actually Is
Pi-hole is a network-level DNS sinkhole. That single sentence hides most of what you need to understand before you install it, so let's unpack it slowly. Every time a device on your network wants to talk to the internet, it almost always starts with a DNS lookup: "what is the IP address of ads.doubleclick.net?" or "where does api.segment.io live?" Pi-hole positions itself as the DNS server your devices ask. Instead of answering honestly, it consults a set of block lists and, when the requested domain is on a list, returns nothing. The browser or app never gets to connect, so the ad or tracker never loads.
The crucial part is
network-level. A browser extension like uBlock Origin only protects the one browser it is installed in, on the one device it runs on. Pi-hole protects everything that uses your network's DNS: phones that won't let you install content blockers, smart TVs with hardcoded ad SDKs, game consoles, IoT bulbs, thermostats, baby monitors, and the laptop whose browser extensions got disabled by a corporate policy. One install, and the whole LAN gets quieter.
It is also deliberately narrow. Pi-hole is not a firewall, not a VPN, not a full authoritative DNS server, and not a content-inspection proxy. It is a focused tool that does one job at the DNS layer. That focus is exactly why it is so popular and so reliable: there is very little surface area to break.
2. The Architecture: One Binary Called FTL
If you installed Pi-hole before 2025, the architecture you remember is gone. The old stack ran a PHP web dashboard on top of a lighttpd web server, with a separate
pihole-FTL daemon doing the DNS work. Version 6, released in February 2025, collapsed that into a single C binary called
pihole-FTL. The web dashboard and the REST API are now served from inside FTL itself. There is no PHP, no lighttpd, and a dramatically smaller install footprint.
FTL is, under the hood, a heavily modified fork of
dnsmasq — the same small DNS forwarder many routers run — plus an embedded web server, a REST API, and a SQLite database that records queries. When you run
pihole from the command line, you are talking to a small shell wrapper that calls into the FTL API. When you open the admin dashboard at port 80 (or 8080 inside the container), you are hitting the same embedded server.
This matters for operators because upgrades became simpler and the runtime got lighter. It also means there is one process to watch, one log to read, and one place to point your monitoring. For a home box that you want to forget about, fewer moving parts is a genuine reliability win.
3. How DNS Blocking Really Works
To appreciate the strengths and limits of Pi-hole, you have to understand the DNS exchange. Your laptop wants
fonts.googleapis.com. It sends a UDP (or TCP) DNS query to whatever server your DHCP handed out as the resolver — which you have pointed at Pi-hole. Pi-hole looks up the domain in Gravity, its compiled block list. If the domain is not blocked, Pi-hole forwards the query to your upstream resolver (Google, Cloudflare, Quad9, or your own recursive Unbound) and returns the answer. If the domain is blocked, Pi-hole answers with
0.0.0.0 (or the configured "blocking mode" address) immediately, with no upstream query at all.
The blocking is therefore upstream of the content. The ad never downloads because the device never learns where to fetch it. This is why Pi-hole saves bandwidth and battery: the request is killed in microseconds, not after a megabyte of JavaScript has loaded and run.
But notice the dependency: blocking only works if the device actually uses Pi-hole as its DNS server. If a phone has "private DNS" (Android's DoT) turned on, or an app ships its own hardcoded resolver, or a laptop has a static DNS of
8.8.8.8, that traffic bypasses Pi-hole entirely. Network-wide blocking is only as strong as your ability to force DNS through Pi-hole — a theme we return to in the limitations section.
4. Block Lists and the Gravity Database
Pi-hole does not invent the domains to block. You subscribe to block lists — plain text files of one domain per line — and Pi-hole compiles them into a database it calls Gravity. The default list on a fresh install is a well-known curated list (the StevenBlack aggregation, which itself merges several sources). From there you can add lists for tracking, malware, phishing, regional ad networks, and more.
Gravity is rebuilt when you run
pihole -g or click "Update Gravity" in the dashboard. It downloads every subscribed list, dedupes domains, applies your allowlist and denylist overrides, and writes a compact SQLite index that FTL queries per request. A modest list set of a few hundred thousand domains builds in seconds on a Pi and consumes only a few dozen megabytes of storage.
The ecosystem around block lists is itself a reason Pi-hole dominates the category. There are community-maintained lists for concrete goals: one list blocks smart-TV telemetry, another blocks coin-miners, another blocks known malware C2 domains. You can be surgical. The risk is the opposite: subscribe to fifteen aggressive lists and you will start breaking legitimate sites, because block lists are human-curated and occasionally wrong. The skill is not "add every list" — it is "add the smallest set that achieves your goal, then allowlist the false positives."
5. Installation: One Script or One Container
There are two supported paths. The first is the famous one-liner:
curl -sSL https://install.pi-hole.net | bash. This runs the official installer on a Debian or Ubuntu host, detects your environment, asks a few questions, and leaves you with a running Pi-hole. The second is the official Docker image,
pihole/pihole, which bundles FTL, the web interface, and the CLI into one Alpine-based container.
For most people the container is the better choice in 2026. It isolates the DNS server from the host, makes updates a tag bump, and composes cleanly next to the rest of a self-hosted stack. You map port 53 (DNS) and port 8080 (admin), mount a volume for
/etc/pihole and
/etc/dnsmasq.d, and set a few environment variables for the admin password and timezone. Within a minute you have a working sinkhole.
Whichever path you choose, the post-install step is the same and it is the one people skip: you must tell your router (or each device) to use Pi-hole as its DNS server. On a home network the cleanest method is to change the DNS handed out by the router's DHCP server to Pi-hole's IP. Then every device that joins picks it up automatically. Until you do this, Pi-hole is installed but doing nothing.
6. The pihole.toml Configuration Model
Version 6 moved all configuration into a single TOML file at
/etc/pihole/pihole.toml. This replaced the scattering of files and environment variables that the v5 era used. The TOML is fully documented inline with comments, and every setting is also reachable through the REST API and the dashboard, so you rarely hand-edit the file — but when you script deployments, editing TOML is far cleaner than shelling out to
pihole subcommands.
A few sections matter most.
dns controls upstream resolvers, blocking mode, and whether Pi-hole also serves DHCP.
webserver controls the admin port and TLS.
gravity controls list update behavior.
query controls logging and the privacy level (how much detail about clients and domains is retained).
ftl controls the database size caps and retention.
Because the file is the single source of truth, backing up Pi-hole is trivial: copy
pihole.toml and the Gravity database. Restore them on a fresh host and you have an identical instance. This is the kind of operational simplicity that makes self-hosting sustainable for one person.
7. The REST API and Web Dashboard
The admin dashboard is a Vue single-page app served by FTL. It shows the query throughput, the percentage blocked, a live query log, top clients, top blocked domains, and a long-term graph of activity. For a privacy-minded household it is oddly satisfying to watch: you see the silent war between your devices and the ad networks, and Pi-hole is winning most of it.
Underneath the dashboard is a REST API (documented and versioned) that returns the same data as JSON. This is what makes Pi-hole scriptable and integrable. You can pull stats into your own dashboards, trigger Gravity rebuilds from a cron job, or flip blocking on and off per client. Authentication is a single admin password (or an app password for the API); there is no user-account system. For a home network that is fine. For a shared organization it is the first thing you will wish were better.
8. Real Self-Hosting Cost Numbers
"Free and open source" is true about the software license, but it is not the whole cost story. Let's put real numbers on running Pi-hole for a year.
Option A — Raspberry Pi Zero 2 W, already owned microSD. Hardware is sunk cost; call it $0 marginal. Idle power draw is about 1.5–2.5 W. At $0.15/kWh that is roughly 0.05 kWh/day, about $2.50–$4/year in electricity. Total: under $5/year.
Option B — Raspberry Pi 4 (2 GB), fresh purchase. Board ~$45, good SD card ~$10. Idle draw ~3 W → ~$4–$6/year electricity. Amortize the $55 hardware over three years and you are at ~$18 + $5 = ~$23/year. Total: ~$23/year.
Option C — Idle x86 mini-PC or home server you already run. Marginal electricity is near zero if the box is on anyway; if Pi-hole is the
reason the box stays on, a 15 W idle server costs ~$20/year just to keep running. Total: $0–$20/year depending on whether the hardware has another job.
Option D — A cloud VPS. Do not do this for your home network; a VPS cannot protect your LAN's DNS unless you VPN everything through it, which adds latency and cost. If you insist, a Hetzner CX11 or RackNerd box is ~$1.50–$3/mo, so ~$18–$36/year — but you have gained nothing over a Pi and lost the local-network benefit.
Compare that to a managed filtering resolver like NextDNS: free tier covers 300k queries/month, paid is about $20–$30/year for more, and the real cost is that every DNS query leaves your network and lands on their infrastructure. Pi-hole's software is free; the only mandatory spend is a few watts of electricity and, optionally, a $15–$55 one-time board. The strategic saving is not the license — it is keeping your query stream on hardware you own.
9. Hardware: Pi, Idle Server, or Nothing
Pi-hole's resource appetite is tiny. The documented minimum is 512 MB RAM and a single core, and in practice it uses a fraction of that. A Pi Zero 2 W handles a busy household's DNS without breaking a sweat; the bottleneck is almost never CPU or RAM but SD-card wear from the query log.
Two practical notes. First, put the query database on something with wear leveling, or lower the privacy level so less is written, or point FTL's database at a RAM disk if you don't need history. SD cards do fail, and a Pi-hole that logs every query forever will eventually wear a cheap card. Second, DNS is latency-sensitive; a Pi on Wi-Fi is workable but a wired Pi or a container on a wired server gives snappier resolution. If your Pi-hole is on Wi-Fi and the AP reboots, your whole network loses DNS until it reconnects — another argument for wired, or for a secondary resolver.
10. Where Your Data Goes / Data Sovereignty
This is the heart of why a self-hoster picks Pi-hole over a SaaS blocker, so let's be precise. Pi-hole logs queries in a SQLite database on the machine it runs on. That database contains, depending on your privacy level, the domain requested, the client that requested it, the time, and whether it was blocked. It does not leave your hardware. Pi-hole has no "call home," no telemetry endpoint, no account cloud. Pi-hole LLC is a US entity, but the software sends them nothing; there is no query stream for any parent company to hold.
The one caveat is your
upstream resolver. By default Pi-hole forwards un-blocked queries to a public resolver (Google, Cloudflare, Quad9). That resolver then sees every domain your network looks up. So "I run Pi-hole" does not, by itself, make your DNS private — it makes your
blocking private. To close that gap you run your own recursive resolver (Unbound) behind Pi-hole so lookups go to the root servers directly, and no single upstream gets a complete picture of your browsing. We cover that next.
The data-sovereignty pitch is therefore two layers: Pi-hole keeps the
decisions and the logs on your metal, and Unbound keeps the
lookups off any vendor's servers. Together they are about as sovereign as consumer DNS gets without running your own root.
11. Upstream Resolvers: Why You Should Add Unbound
Out of the box Pi-hole forwards to a public resolver. That is fine for blocking, but it means Cloudflare or Google learns your DNS habits. The well-trodden fix is to install
unbound on the same host, configure it as a validating recursive resolver, and point Pi-hole's upstream at
127.0.0.1#5335 (or whatever port you chose). Now Pi-hole asks Unbound, and Unbound walks the DNS hierarchy from the root, caching as it goes.
The benefits: no single upstream sees your full query history; you are not dependent on one vendor's uptime or policy; and after the cache warms, many lookups are answered locally and are faster. The costs: the first resolution of a brand-new domain is slower because Unbound has to traverse the hierarchy, and you take on a tiny bit of recursive-resolver maintenance (keeping root hints current, which Unbound largely does itself). For a privacy-focused self-hoster this trade is a no-brainer, and the Pi-hole docs ship a known-good Unbound config.
12. DoH, DoT, and the Encrypted DNS Problem
Modern operating systems and browsers increasingly push encrypted DNS — DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) — to defeat surveillance and tampering. That is good for user privacy against ISPs, but it is a problem for Pi-hole, because if a client resolves through Cloudflare's DoH endpoint directly, it never asks your Pi-hole.
There are three responses. The strict one is to block known DoH/DoT endpoints at the firewall so clients are forced back to your plain DNS (which Pi-hole answers). The cooperative one is to enable DoH
on Pi-hole's upstream (FTL can use encrypted upstreams) so your link to the resolver is encrypted even though your LAN stays plain. The honest one is to accept that a determined device or app can bypass you, and that Pi-hole is one layer of a defense, not the whole wall. If your threat model includes "my own phone is trying to evade my blocker," you will need device-level controls (MDM, locked DNS, or just not installing those apps), not DNS trickery.
13. DHCP, VLANs, and Multi-Subnet Homes
Pi-hole can also be your DHCP server, which is handy when your router won't let you change the DNS option it hands out (some ISP routers are locked down). Enabling Pi-hole's DHCP and disabling the router's means every lease gets Pi-hole as DNS automatically. The catch: now Pi-hole is critical infrastructure twice over — if it dies, new devices can't even get an IP. Run a secondary or keep the router's DHCP ready to flip back.
For advanced networks with VLANs — say, an IoT VLAN separate from your laptops — DNS gets fiddly. The IoT devices must be able to reach Pi-hole's IP on port 53, which means firewall rules allowing cross-VLAN DNS. Many people put Pi-hole on the management VLAN and open just port 53 to IoT. Getting this wrong produces the classic "why is the smart bulb offline" mystery. Plan the firewall rules before you split the network.
14. Performance and Scale: How Many Queries
A modern home throws a surprising number of DNS queries — often 50,000 to 200,000 per device per day when you count all the background telemetry. Pi-hole answers these in microseconds from RAM/SQLite and barely notices. FTL handles millions of queries per day on a Pi 4. Even a small office of a few dozen people is trivial.
The thing that actually scales is your block-list size and your log retention. A few hundred thousand blocked domains is nothing; several million starts to matter for Gravity build time and memory. The query log, if kept at full detail forever, grows without bound and eventually stresses the SD card (see the hardware note). Set a privacy level and a database size cap, and Pi-hole will run for years unattended.
15. High Availability and Failover
Pi-hole has no built-in clustering. If your one Pi-hole goes down, DNS for the network goes down with it — unless you planned ahead. The standard patterns:
- Two Pi-holes, two IPs. Hand out both as primary and secondary DNS via DHCP. Clients that honor the secondary keep working when the primary fails. This is the simplest and most common setup.
- Keep the router as secondary. Risky, because then blocked domains start leaking through the router's resolver during an outage — better than no DNS, worse than protected DNS.
- External sync. Tools exist to sync Gravity and config between two Pi-holes so they stay identical. Useful if you curate a lot of custom lists.
The honest takeaway: for a home network, one Pi wired to the router is enough because outages are rare and brief. For anything business-adjacent, run two and accept the small sync overhead. There is no magic "Pi-hole cluster" button, and the project is clear that HA is your responsibility.
16. Honest Limitations
No tool this popular is without sharp edges, and the marketing rarely lists them. Here is the unvarnished version.
- DNS-layer only. Pi-hole blocks at the domain level. It cannot remove ads embedded in the page HTML from the same domain as the content (most banner spots served by the publisher's own CDN), and it cannot touch ads delivered over HTTPS from non-blocked domains. It is not a substitute for a browser content blocker; it is a complement.
- YouTube, Twitch, and sponsored content survive. Video platforms serve ads from the same domains as the videos. Blocking those domains breaks the video. So Pi-hole does essentially nothing for YouTube ads, and anyone promising otherwise is selling something.
- In-app and hardcoded-IP ads survive. Apps that bundle ad content from their own API, or that connect to raw IP addresses, bypass DNS entirely.
- Breakage is real. Block a list too aggressively and your bank's widget, your thermostat's cloud, or a government site stops working. You will spend time allowlisting. This is the permanent tax of running a sinkhole.
- Single admin, no SSO/RBAC. One password protects the dashboard. There is no multi-user, no roles, no audit log per person. Fine at home, awkward at work.
- It is a single point of failure for DNS. Plan for it (see HA).
- Encrypted client DNS bypasses it unless you enforce otherwise (see DoH/DoT).
None of this makes Pi-hole bad. It makes it a specific tool. Know what it is not, and you will not be angry at it later.
17. Common Pitfalls and Breakage
The support forums are full of a few repeat offenders. First, people install Pi-hole and forget to repoint DNS, then wonder why nothing changed — check that clients actually show Pi-hole as their resolver. Second, they subscribe to every block list they can find, break half the internet, and blame Pi-hole; the fix is fewer lists plus targeted allowlists. Third, they run it on Wi-Fi and blame Pi-hole for "DNS outages" that are really AP reboots. Fourth, they set the privacy level to maximum logging and cook an SD card in a year.
A subtler one: if you enable Pi-hole's DHCP and your router's DHCP is still on, you get two servers handing out addresses and chaos. Disable one. And if you change the admin password via the dashboard but also set it in the container env, the env may override on restart — pick one mechanism.
18. Privacy Trade-offs: What Blocking Does and Doesn't Do
It is worth separating three different privacy claims people make about Pi-hole.
Claim 1: "Pi-hole stops trackers." Mostly true at the network level — it blocks known tracking domains for every device. It does not stop first-party tracking (the site you are on logging your behavior) or fingerprinting that needs no third-party domain.
Claim 2: "Pi-hole makes my DNS private." Only if you also run your own recursive resolver. With a public upstream, the upstream still sees your lookups. Pi-hole makes the
blocking private; Unbound makes the
lookups private.
Claim 3: "Pi-hole hides my browsing from my ISP." Not by itself — your ISP still sees the IPs you connect to and, for non-DoH, can infer destinations. A VPN or Tor hides destination; Pi-hole does not.
Stated plainly: Pi-hole is a tracking-reduction and bandwidth-saving tool, not an anonymity tool. Pair it with Unbound, a VPN for sensitive traffic, and browser-level blockers, and you get layered privacy. Pi-hole alone is one solid layer, not the whole stack.
19. Pi-hole vs AdGuard Home vs NextDNS
Pi-hole's closest sibling is AdGuard Home, which is also a self-hosted DNS sinkhole with a slick dashboard, native DoH/DoT, and a few quality-of-life features Pi-hole lacks (per-client rules in the UI, built-in safe-browsing). Pi-hole's advantages are ecosystem maturity, block-list breadth, and the v6 single-binary simplicity. AdGuard Home is a fair choice if you want those extras without adding Unbound yourself.
NextDNS is the SaaS version of the same idea: no server to run, great lists, and encrypted upstreams built in — but every query goes to their cloud, and you pay (or hit a free-tier cap). The trade is convenience versus data sovereignty, exactly the trade this blog keeps returning to. If you cannot keep a server running, NextDNS is the pragmatic pick; if you can, Pi-hole (with Unbound) keeps your data home.
20. Security Hardening
A DNS server is a small but real attack surface, and it is on your network answering queries. Basics: don't expose port 53 to the public internet — bind Pi-hole to your LAN only, and never port-forward 53. Put the admin dashboard behind a reverse proxy with TLS and, ideally, an additional auth layer (a VPN or SSO proxy) rather than the single password alone. Keep the OS patched; FTL has had occasional security fixes (the July 2026 wave included a couple), so updating promptly matters.
If you run the container, pin a specific version tag instead of
latest so an update can't surprise you, and review changes before bumping. And keep Pi-hole off the public internet even if you travel — if you need DNS on the road, use a VPN back to your network, not an exposed resolver.
21. Integrating with the Rest of Your Stack
Pi-hole slots neatly into a self-hosted homelab. Point your reverse proxy's upstream services at it for name resolution. Scrape its API or its Prometheus endpoint (FTL exposes metrics) into your monitoring so you get an alert when block rate spikes or resolution latency climbs. If you run a dashboard like Homarr or Heimdall, drop the admin link there. If you run a recursive resolver, document the dependency order: Unbound must be up before Pi-hole answers anything not cached.
For households, the nicest integration is a "pause blocking" button on a wall display or a Home Assistant entity, so a guest can temporarily unblock without you handing over the admin password. Pi-hole's API makes this a ten-minute automation.
22. Maintenance and Updates
Ongoing care is light. Update Gravity weekly (the dashboard can auto-update lists on a schedule). Update Pi-hole itself when a new release drops — the v6 series ships security fixes regularly, so don't sit on old versions. On the container, that means pulling a newer tag; on bare metal,
pihole -up. Watch the SD card health if you log heavily; set a privacy level that discards detail after a few days if you don't need history.
Backups are one file:
pihole.toml plus the Gravity DB. Snapshot them to your normal backup target. A full rebuild from backup takes minutes, which means a dead Pi is an annoyance, not a project.
23. Who Should Actually Run This
Run Pi-hole if you operate a home or small-office network and you are willing to spend an hour on setup and occasional allowlisting. The payoff — quieter devices, less bandwidth, fewer trackers, and a query log that stays yours — is real and durable. It is one of the highest "effort-to-benefit" ratios in self-hosting.
Skip it if you cannot keep a server or Pi running, or if your only goal is hiding from your ISP (get a VPN instead), or if you specifically want YouTube ads gone (no DNS tool does that). And if you manage a large organization with compliance and role requirements, treat Pi-hole as a personal/privacy layer, not your enterprise DNS platform — it has no SSO, RBAC, or HA story of its own.
24. A Practical First-Week Checklist
If you want Pi-hole to stick rather than become another abandoned container, the first week is where it is won or lost. Here is the sequence that works for most people.
Day 0 — Install and prove it works. Stand up the container or run the installer. Before you touch any router setting, open the dashboard and confirm Pi-hole can resolve a test domain by setting your laptop's DNS manually to the Pi-hole IP. You should see queries appear in the live log. This isolates "Pi-hole runs" from "my network uses it," and saves confusion later.
Day 1 — Repoint DNS the safe way. Change the router's DHCP DNS option to Pi-hole, but keep a note of the original value. Watch the client list grow over 24 hours. If something critical breaks, you can flip the router back in thirty seconds. Do not enable Pi-hole's own DHCP yet; one DHCP server at a time.
Day 2 — Tune the lists. Start with the default list only. After a day, look at "Top Blocked" and decide if you want more coverage. Add one curated list at a time, not ten at once. If a site you need breaks, use the query log to find the blocked domain and allowlist just that domain — never disable blocking globally to fix one site.
Day 3 — Add Unbound (optional but recommended). If privacy matters to you, install Unbound and point Pi-hole's upstream at it. Verify with a
dig that resolution still works and that the upstream is now local. This is the difference between "my blocking is private" and "my DNS is private."
Day 4 — Set retention and backups. Lower the privacy level or cap the database so your SD card is not written to death. Copy
pihole.toml and the Gravity DB to your backup target. Schedule a weekly Gravity update.
Day 5 — Harden the edge. Confirm port 53 is not exposed to the internet. Put the admin dashboard behind TLS and, if you can, an extra auth layer. Pin the container image to a specific version tag.
Day 6 — Monitor it. Add Pi-hole to your monitoring (scrape the API or metrics) so you get alerted on resolution failures. If you run Home Assistant, expose a "pause blocking" entity for guests.
By the end of the week you should have a sinkhole that blocks the obvious junk, logs nothing you don't want, survives a reboot, and alerts you when it is unhappy. That is a finished Pi-hole, not a project. The people who quit are usually the ones who subscribed to fifteen lists on day one and spent the weekend allowlisting their bank.
One more habit worth building: review the "Top Clients" and "Top Blocked" views once a month. They tell you which devices are chatty and which trackers are most aggressive on your network, and they are a quiet reminder of why you self-host in the first place. The dashboard is not just a control panel; it is a small window into who is actually trying to watch you.
25. Bottom Line
Pi-hole is the rare piece of self-hosted software that does one thing, does it well, and asks almost nothing of you in return. For the price of a few watts of electricity — or a one-time $15–$55 board if you have nothing to reuse — you get network-wide ad and tracker blocking for every device you own, with a query log that never leaves your hardware and a license (EUPL-1.2) that keeps it yours forever. Version 6's single-binary FTL design made it lighter and simpler than ever, and the block-list ecosystem means you can tune it from "block the obvious ad networks" to "block telemetry, malware, and regional junk" with a few subscriptions.
The honest caveats are narrow but real: it is DNS-layer only, so in-page and YouTube ads survive; aggressive lists cause breakage you must allowlist away; there is no SSO or built-in HA; and encrypted client DNS can bypass it unless you enforce otherwise. Pair it with your own Unbound recursive resolver and you close the last privacy gap, keeping both the blocking decisions and the raw lookups on metal you control. For a self-hoster who cares about data sovereignty, Pi-hole is not optional reading — it is one of the first things you should stand up.
Related
Comments (0)
No comments yet. Be the first to comment!