Ad networks and trackers do not stop at your browser. They ride along inside mobile apps, smart TVs, streaming boxes and IoT gadgets that have no extension store and no privacy settings worth trusting. Pi-hole closes that gap by filtering every device on a network at the DNS level, before a single ad request ever reaches your router. The project’s current release stack is FTL v6.8, Web v6.6.1 and Core v6.5, all published together on October 17, 2026, building on the v6.0 rewrite that shipped February 18, 2025, a rewrite that needed a pair of quick follow-up fixes, v6.0.1 and v6.0.2, within weeks of that initial February 2025 launch, and the v6.4.2 point release from April 24, 2026. This tutorial walks through a full install on Raspberry Pi and Docker, upstream DNS hardening with Unbound and cloudflared, blocklist tuning, and the troubleshooting steps that come up most often once Pi-hole becomes the only DNS resolver on a home or small-office network.
Pi-hole is a DNS sinkhole. Its own documentation describes it plainly: “The Pi-hole® is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.” Instead of blocking ads per-browser, it intercepts the DNS lookups that ad and tracking domains depend on and returns nothing, so the request dies before a connection is even opened. The Raspberry Pi Foundation’s own tutorial sums up the mechanism the same way: “Pi-hole blocks ads by acting as a DNS sinkhole.” That single design choice is why one Pi-hole install can protect a game console, a smart fridge and a work laptop simultaneously, with zero per-device configuration beyond pointing DHCP at it.
Don't miss new tech stories on Google
Add Tech Insider once in the Google app and our stories appear in your news suggestions.
What Pi-hole Actually Does (and What It Doesn’t)
Pi-hole runs a lightweight DNS server called FTLDNS that answers lookups for every device configured to use it, then checks each queried domain against one or more blocklists. If a domain matches a list, Pi-hole returns a null response instead of the domain’s real IP address, and the ad, tracker or malware callback never loads. If the domain is clean, Pi-hole forwards the query to an upstream resolver (Cloudflare, Google, Quad9, or a resolver you run yourself) and passes the answer back. The project’s homepage puts the practical benefit in plain terms: network-level blocking reaches “ads in places a browser extension can’t reach, such as mobile apps, smart TVs and IoT devices, whatever the hardware or OS,” according to Pi-hole’s official site.
It is worth being precise about the limits. Pi-hole blocks by domain name, so it cannot strip ads served from the same domain as legitimate content (a common YouTube complaint), and it does nothing for ads embedded inside an app’s own first-party servers. It is also not a firewall, an antivirus, or a VPN. It reduces the attack surface by cutting off known malicious and advertising domains at the DNS layer, and it gives you visibility into what every device on your network is actually trying to reach. Pair it with a router-level firewall for full coverage; treat Pi-hole as the DNS filtering layer, not a replacement for endpoint security.
Why DNS-Level Blocking Matters for Network Security
Ad blocking is the headline feature, but the security case for a DNS sinkhole is arguably the stronger one. A large share of malware families, from banking trojans to IoT botnets, rely on DNS to reach command-and-control (C2) infrastructure, check in for instructions, or exfiltrate data. Phishing kits and malicious redirect chains also depend on DNS lookups succeeding before a payload ever loads in a browser. By filtering at the DNS layer, Pi-hole blocks a meaningful category of that traffic before a TCP connection is even opened, which is a different (and in some ways more resilient) layer of defense than an endpoint antivirus that has to inspect a payload after the fact.
This matters most on networks with devices that cannot run endpoint security software at all: smart TVs, streaming sticks, connected doorbells, thermostats, and the dozens of other IoT devices that now sit on a typical home or small-office network. None of those devices support a security agent, but all of them use DNS, which means all of them benefit automatically the moment Pi-hole becomes the network’s resolver. Several public malware and adware blocklists, including ones compatible with Pi-hole’s Adlists format, specifically track known C2 domains, so adding one alongside a standard ad/tracker list extends Pi-hole’s role from an ad blocker into a lightweight network security control. It does not replace a firewall, intrusion detection system, or endpoint protection, but it closes a gap none of those tools cover well: devices with no client-side software running at all.
Prerequisites and Version Requirements
Pi-hole’s official prerequisites page, last updated September 23, 2026, lists modest minimums: 512MB of RAM and 2GB of free disk space, with 4GB of storage recommended for a comfortable install. Confirm what you need before you start:
| Requirement | Minimum | Recommended |
|---|---|---|
| Pi-hole version | Core v6.0 or later | Core v6.5 (latest, October 17, 2026) |
| RAM | 512MB | 2GB+ if also running Unbound or Docker apps alongside it |
| Storage | 2GB free | 4GB+ (more if you keep long query-log history) |
| Operating system | Debian, Ubuntu, Fedora, CentOS Stream, or any Docker host | Raspberry Pi OS Lite (64-bit) or Ubuntu Server LTS |
| Network | Static IP or DHCP reservation for the Pi-hole host | Static IP set at the router, not just the OS |
| Access to router settings | Ability to change DHCP DNS option | Admin login to set Pi-hole as the sole DNS server |
You do not need a Raspberry Pi specifically. Pi-hole runs identically on a Raspberry Pi 3, 4 or 5, an old laptop repurposed as a Linux box, a $35 mini PC, a VM on a NAS, or inside Docker on almost anything. The name is a legacy of the original 2015 project, not a hardware requirement. What matters is that the host stays on 24/7, because if it goes offline, every device pointed at it for DNS loses internet name resolution until you either fix Pi-hole or fall back to a secondary DNS server.
Choosing Where to Run Pi-hole: Raspberry Pi vs Mini PC vs NAS
Every hardware option below can run Pi-hole comfortably given the modest 512MB RAM minimum, so the real decision comes down to reliability, power draw and what you already own. A Raspberry Pi remains the most common choice because it’s small, uses under 5 watts, and has an enormous base of community tutorials if something goes wrong, although Raspberry Pi raised the prices of the 2GB Raspberry Pi 4 and Raspberry Pi 5 by $12.50 each on October 1, 2026, while the 1GB variants stayed unchanged. A used business mini PC (the kind of $50-$100 refurbished unit common on the secondary market) is a solid alternative if you want a bit more headroom for running Unbound and a handful of Docker containers on the same box. Running Pi-hole as a container on an existing NAS (Synology, QNAP, TrueNAS) or hypervisor (Proxmox, ESXi) is the most efficient option if you already leave that hardware powered on 24/7, since it avoids adding a second always-on device to your electricity bill entirely.
| Platform | Typical Power Draw | Best For | Setup Method |
|---|---|---|---|
| Raspberry Pi 4/5 | ~3-7W | First-time setup, dedicated appliance | Native installer on Raspberry Pi OS Lite |
| Used mini PC | ~10-20W idle | Running Unbound + Pi-hole + other services together | Native installer on Ubuntu Server or Debian |
| NAS (Synology/QNAP/TrueNAS) | Marginal (already running) | Households that already run a NAS 24/7 | Official Docker image |
| Proxmox/ESXi VM or LXC | Marginal (already running) | Home labs with an existing hypervisor | Native installer inside a lightweight LXC/VM |
Step 1: Choose Your Installation Method
Pi-hole supports three realistic paths in 2026: the official one-line installer on bare metal or a VM, a Docker container, or installation inside an existing home-server stack (TrueNAS, Unraid, Proxmox LXC). The one-line installer is fastest for a dedicated Raspberry Pi. Docker is the better choice if you already run a hypervisor or NAS and want Pi-hole isolated with a defined resource limit and easy backups via a mounted volume. This tutorial covers both, starting with the native installer, then the Docker equivalent in Step 6.
Step 2: Flash the OS and Set a Static IP
If you are using a Raspberry Pi, flash Raspberry Pi OS Lite (64-bit) with Raspberry Pi Imager, enabling SSH and setting a username/password during the flashing wizard so you can boot headless. Before installing Pi-hole, lock in a static IP for the host, either through your router’s DHCP reservation list (preferred, since it survives OS reinstalls) or by editing the OS network config directly. Every device on the network is going to be told “use this exact IP for DNS,” so that IP cannot be allowed to drift.
# Check current IP and interface on the Pi-hole host
ip addr show
# Example: reserve 192.168.1.10 for this device's MAC address
# in your router's DHCP settings, then reboot the Pi-hole host
# to confirm it picks up the reserved address
sudo rebootStep 3: Run the Official Installer
Pi-hole’s documented installation method is a single curl-to-bash command that downloads and runs the interactive installer:
curl -sSL https://install.pi-hole.net | bashIf you would rather review the script before running it as root, which is a reasonable habit for anything piped into bash, clone the repository and run the local copy instead:
git clone --depth 1 https://github.com/pi-hole/pi-hole.git
cd pi-hole/automated%20install/
sudo bash basic-install.shThe installer’s text-based wizard walks through: choosing your upstream DNS provider (Cloudflare, Google, Quad9, OpenDNS, or a custom resolver), selecting a default blocklist, choosing IPv4/IPv6, and confirming your static IP. At the end it prints an admin web password. Write it down; you will need it immediately for the dashboard, and you can always reset it later with pihole -a -p.
Step 4: Verify the Install and Log In to the Dashboard
Once the installer finishes, confirm the FTL DNS service is active and reachable:
pihole status
sudo systemctl status pihole-FTL
# Expected output includes:
# [i] Pi-hole blocking is enabled
# Active: active (running)Open a browser on any device on the same network and navigate to http://<pi-hole-ip>/admin. Log in with the password from the installer. The dashboard shows a live query log, a blocking percentage, top blocked domains and top clients, updating within seconds of the first devices sending it DNS traffic.
Step 5: Point Your Router’s DHCP at Pi-hole
Pi-hole only filters traffic from devices that actually use it as their DNS server, so the network-wide win comes from setting it at the router, not per-device. As Pi-hole’s own site instructs: “Point your router’s DHCP settings at Pi-hole so every device on your network uses it automatically.” Log into your router’s admin panel, find the DHCP or LAN settings, and set the primary DNS server to your Pi-hole’s static IP. Leave the secondary DNS field blank or point it at Pi-hole’s IP again rather than a public resolver, otherwise some devices will silently bypass Pi-hole by falling back to the secondary server whenever it responds faster.
Existing devices will keep using their old DNS settings until their DHCP lease renews, which can take anywhere from a few hours to several days depending on your router’s lease time. To force it immediately on a device, disconnect and reconnect it to Wi-Fi, or run the platform-specific release/renew commands (ipconfig /release && ipconfig /renew on Windows, disabling and re-enabling the network interface on macOS and Linux).
Step 6: Alternative Path: Deploy Pi-hole With Docker
If you are running a NAS, a home server, or a Proxmox box, Pi-hole’s official Docker documentation (updated April 6, 2026) recommends mapping DNS ports 53/tcp and 53/udp along with the admin web port. The official pihole/pihole image has shipped a steady cadence of releases since the first v6-based image, 2025.02.0, arrived on February 18, 2025 (2025.11.1 in November 2025, 2026.02.0 in February 2026, 2026.04.0 in April 2026, 2026.05.0 in May 2026, 2026.06.0 in June 2026, 2026.07.0 in July 2026 and 2026.10.0 on October 17, 2026, the tag that carries FTL v6.8, Web v6.6.1 and Core v6.5), so pulling the latest tag keeps you current with each of those point releases automatically. Pi-hole’s Docker documentation also warns that versions after 2025.02.0 contain breaking changes from 2024.07.0 or older, so anyone upgrading an old container should read the release notes first. A minimal docker-compose.yml looks like this:
version: "3"
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
ports:
- "53:53/tcp"
- "53:53/udp"
- "80:80/tcp"
environment:
TZ: 'America/New_York'
FTLCONF_webserver_api_password: 'change-this-password'
volumes:
- './etc-pihole:/etc/pihole'
- './etc-dnsmasq.d:/etc/dnsmasq.d'
restart: unless-stoppedBring it up with docker compose up -d. Because port 53 is a privileged low port that many Linux distributions already bind for their own local resolver (systemd-resolved is the usual culprit), you may need to disable the host’s built-in DNS stub listener before the container can claim port 53. That single conflict is the single most common reason a fresh Docker install of Pi-hole fails to bind on the first attempt.
Step 7: Add and Tune Blocklists
A default install ships with a starter blocklist, but most users add at least one aggregated list for meaningfully better coverage. The most widely used community list is the StevenBlack hosts file, hosted at github.com/StevenBlack/hosts, which merges multiple ad, tracking and malware-domain lists into one deduplicated file. Add lists from the admin dashboard under Group Management → Adlists, paste the raw URL, then run:
pihole -g
# Output:
# [i] Neutrino emissions detected...
# [i] Target: raw.githubusercontent.com (StevenBlack hosts)
# [✓] Status: Retrieval successful
# [i] Number of gravity domains: 190000+ (varies by list combination)pihole -g is the “gravity” update command that rebuilds Pi-hole’s blocking database from every subscribed list. Run it manually after adding a list, and note that Pi-hole schedules it automatically afterward (weekly by default) so lists stay current without intervention.
Step 8: Add a Recursive Resolver With Unbound for DNSSEC
By default, Pi-hole forwards unblocked queries to a public upstream like Cloudflare or Google, which means that provider still sees every domain you visit, just not the ones Pi-hole already filtered. Running Unbound as a local recursive resolver removes that third party entirely: Pi-hole talks to Unbound, and Unbound talks directly to the DNS root servers. Pi-hole’s own Unbound guide, updated September 12, 2026, confirms there are “no additional hardware requirements” to run it alongside Pi-hole on the same box.
sudo apt install unbound
sudo service unbound restart
# Test resolution and DNSSEC validation
dig pi-hole.net @127.0.0.1 -p 5335
dig +ad dnssec.works @127.0.0.1 -p 5335
# A valid DNSSEC response includes the "ad" (authenticated data) flagAfter confirming Unbound answers on port 5335, set it as Pi-hole’s only upstream DNS server in the admin dashboard under Settings → DNS, using 127.0.0.1#5335 as a custom upstream. This is the setup most privacy-focused home labs converge on: Pi-hole for filtering, Unbound for resolution, no third-party DNS provider in the loop at all.
Step 9: Encrypt Upstream Queries With Cloudflared (Optional Alternative to Unbound)
If you would rather keep a fast public upstream but stop your ISP from seeing plaintext DNS queries in transit, Pi-hole’s cloudflared guide (updated February 12, 2026) documents running Cloudflare’s cloudflared daemon as a local DNS-over-HTTPS proxy instead of Unbound. This is a meaningfully different trade-off from Unbound: you get encryption in transit, but Cloudflare (or whichever provider you configure) still sees the query.
sudo systemctl enable cloudflared
sudo systemctl start cloudflared
sudo systemctl status cloudflared
# Then set Pi-hole's upstream DNS to 127.0.0.1#5053 in the admin dashboardChoose one path, not both: Unbound for full recursive resolution with no third-party visibility, or cloudflared for encrypted-in-transit queries to a provider you trust. Running both at once on the same upstream slot just adds a redundant hop.
Step 10: Configure Local DNS Records and Conditional Forwarding
Once Pi-hole is the network’s only DNS server, it is also the natural place to manage local hostnames for other devices on your LAN (a NAS, a media server, a self-hosted app) without editing every client’s hosts file. Under Local DNS → DNS Records in the admin dashboard, add entries mapping a hostname to a LAN IP, for example nas.home.lan → 192.168.1.20. If you want Pi-hole to resolve your router’s own device list by hostname (so client names show up correctly in the query log instead of raw IPs), enable Conditional Forwarding under Settings → DNS and point it at your router’s IP with your LAN’s subnet.
Step 11: Set Up a Secondary Pi-hole for Redundancy
A single Pi-hole is a single point of failure for your entire network’s name resolution. If it goes down for an update, a reboot, or a hardware fault, every device configured to use only that IP for DNS loses internet access until it’s back. The standard fix is a second, independent Pi-hole instance on separate hardware, synced with Gravity Sync or Orbital Sync (both community tools, not part of core Pi-hole) so blocklists and settings stay identical across both. Set your router’s primary DNS to Pi-hole #1 and secondary DNS to Pi-hole #2, so clients automatically fail over.
Step 12: Lock Down Remote and Admin Access
Pi-hole’s admin dashboard should never be exposed directly to the public internet. It has no built-in HTTPS by default (you’d need to configure lighttpd manually for that, per the AdGuard Home comparison on GitHub), and the DNS service itself should only answer queries from your LAN’s IP range. If you need remote access to check the dashboard while away from home, use a VPN back into your network (WireGuard or your router’s built-in VPN server) rather than port-forwarding 80 or 443 to the Pi-hole host. Also change the default admin password immediately after install with pihole -a -p, and keep the OS itself patched with regular apt update && apt upgrade runs, since Pi-hole’s own security posture depends on the underlying Linux host being current.
Pi-hole vs. AdGuard Home: Choosing Your DNS Filtering Layer
Pi-hole is not the only network-wide DNS blocker, and it is worth understanding where it differs from its closest rival before committing a weekend to either. AdGuard Home’s own project comparison, maintained on its GitHub wiki, lays out the split clearly: AdGuard Home ships with encrypted DNS upstream and inbound support (DNS-over-HTTPS, DNS-over-TLS and DNSCrypt) built into a single Go binary, along with a DHCP server and HTTPS for its own admin interface out of the box. Pi-hole requires the additional Unbound or cloudflared setup covered in Steps 8 and 9 to reach comparable encryption, and its admin interface needs manual lighttpd configuration for HTTPS.
| Feature | Pi-hole (Core v6.5) | AdGuard Home |
|---|---|---|
| Encrypted upstream DNS (DoH/DoT/DoQ) | Bolt-on via cloudflared or Unbound | Built in natively |
| Serving encrypted DNS to clients | Requires additional software | Built in natively |
| HTTPS admin interface | Manual lighttpd configuration | Built in |
| DHCP server | Available, less commonly used | Built in |
| Cross-platform native binary | Linux/Docker only | Linux, macOS, Windows, cross-platform |
| Latest stable release | Core v6.5 (October 17, 2026) | Actively released, check GitHub for current tag |
| Community blocklist ecosystem | Very large (StevenBlack, OISD, others) | Large, overlapping lists supported |
Neither tool is objectively “better” in every scenario. Pi-hole’s advantage is its maturity, its huge base of tutorials and community blocklists, and a dashboard many users find more approachable for a first home-lab project. AdGuard Home’s advantage is fewer moving parts if you want encrypted DNS without manually standing up Unbound or cloudflared as separate services. Plenty of home labs run one as primary and the other as the failover resolver described in Step 11, since they don’t share a codebase and a bug in one is unlikely to affect the other.
Common Pitfalls When Setting Up Pi-hole
Most Pi-hole support requests trace back to a handful of repeat mistakes. Watching for these up front saves a lot of debugging later.
- Setting a DHCP reservation instead of a true static IP at the OS level, then having the router’s DHCP scope change later and orphan the reservation. Confirm the IP with
ip addr showafter every reboot for the first week. - Leaving a secondary DNS field pointed at a public resolver on the router. Some devices race both DNS servers and use whichever answers first, silently bypassing Pi-hole’s filtering for a meaningful share of queries.
- Forgetting that systemd-resolved already owns port 53 on many Debian/Ubuntu hosts, which causes the Pi-hole installer or Docker container to fail to bind DNS with a port-already-in-use error.
- Over-blocking with too many aggressive lists at once, breaking legitimate services like banking apps, game logins, or smart-home integrations that route through domains that look tracker-like but are functionally required.
- Never rotating the admin password from the installer’s auto-generated one, especially on a box that also runs other exposed services.
- Running only one Pi-hole instance with no secondary DNS server configured, so a single reboot or SD-card failure takes down internet access for the whole house.
- Ignoring gravity update failures silently logged when a blocklist URL goes offline or is rate-limiting Pi-hole’s fetch requests, leaving the install using a stale list without any visible warning on the dashboard.
Troubleshooting Guide
These are the issues that come up most often once Pi-hole is deployed as the sole DNS resolver on a network.
- Devices lose internet access entirely after switching DNS to Pi-hole. Check
pihole statusandsudo systemctl status pihole-FTLon the host; if FTL isn’t running, restart it withsudo systemctl restart pihole-FTLand checkpihole -dfor a debug log. - “Address already in use” when starting the Docker container. Disable the host’s local DNS stub listener (commonly systemd-resolved) or move Pi-hole to a dedicated host/VM that isn’t also running its own resolver on port 53.
- Dashboard shows 0% blocking despite lists being added. Run
pihole -gmanually to rebuild the gravity database; a list addition doesn’t take effect until gravity is regenerated. - A specific site breaks after enabling a blocklist. Search the domain in Pi-hole’s Query Log, identify which list is blocking it, and add it to the Whitelist under Domains rather than disabling the whole list.
- Query log shows queries from an unexpected upstream IP instead of your devices. This usually means a router or device has DNS-over-HTTPS hardcoded (common on some phones and Firefox’s default DoH setting), bypassing Pi-hole entirely; disable app-level DoH or block outbound port 853/443 to known DoH providers at the firewall.
- DNSSEC validation fails after configuring Unbound. Confirm system time is correct with
timedatectl, since DNSSEC signature validation fails on hosts with a wrong clock; then re-test withdig +ad dnssec.works @127.0.0.1 -p 5335. - Web admin interface is unreachable but DNS still resolves. Check that lighttpd is running with
sudo systemctl status lighttpd, and confirm nothing else (another Docker container, a reverse proxy) is already bound to port 80 on that host. - Gravity update fails with a list retrieval error. Check the specific adlist URL for a redirect or outage by curling it directly from the Pi-hole host; dead or renamed list URLs are a common cause after a list maintainer reorganizes their repository.
Advanced Tips for a Production-Grade Home Lab Setup
Once the base install is stable, a few refinements turn a weekend project into infrastructure you can trust for years. First, back up configuration regularly with pihole -a -t, which exports settings, blocklists and local DNS records to a single archive you can restore on new hardware in minutes, this matters more on Pi-hole v6 than it did on older releases, since the Pi-hole project has documented that v6 upgrades are one-way operations with no supported downgrade path, so taking that backup before running pihole -up is not optional busywork but the only safety net you get. Second, if you’re running Docker, mount the /etc/pihole and /etc/dnsmasq.d volumes on persistent storage outside the container so an image update never wipes your configuration. Third, review the Query Log’s “Upstream” column periodically; it’s the fastest way to spot a device that has quietly switched to hardcoded DNS-over-HTTPS and is bypassing your filtering entirely, which is increasingly common on modern phones and browsers that enable DoH by default. Fourth, if you’re pairing Pi-hole with a segmented network (a guest VLAN, an IoT VLAN), set up separate client groups in Pi-hole so IoT devices get a stricter blocklist than trusted client devices, since IoT firmware is far more likely to phone home to advertising and telemetry domains than a laptop. Finally, monitor disk usage on the host: the FTL database logging every query can grow steadily on a busy network, so set a log rotation policy under Settings → Privacy rather than letting it accumulate indefinitely on a small SD card.
Complete Working Project: A Hardened Home Pi-hole Stack
Putting every step together, a complete and hardened Pi-hole deployment for a home network looks like this: a dedicated low-power host (Raspberry Pi 4/5 or an equivalent mini PC) running Raspberry Pi OS Lite with a router-reserved static IP; Pi-hole Core v6.5 installed via the official script; Unbound running locally on port 5335 as the sole upstream resolver, eliminating any third-party DNS provider from the path entirely; the StevenBlack hosts list plus one supplemental list added and rebuilt with pihole -g; router DHCP pointed at the Pi-hole IP as primary DNS with a second Pi-hole instance (synced via a community tool like Gravity Sync) as secondary DNS for failover; admin access restricted to the LAN and reachable remotely only over a WireGuard VPN tunnel; and a weekly cron job running pihole -a -t to back the configuration up to network storage. That combination delivers network-wide ad and tracker blocking, DNSSEC-validated recursive DNS with no third-party visibility into your browsing, and redundancy against the single point of failure that trips up most first-time Pi-hole installs.
#!/bin/bash
# Weekly Pi-hole backup cron job
# Add via: crontab -e
# 0 3 * * 0 /home/pi/pihole-backup.sh
BACKUP_DIR="/mnt/nas/pihole-backups"
DATE=$(date +%Y-%m-%d)
mkdir -p "$BACKUP_DIR"
pihole -a -t "$BACKUP_DIR/pihole-backup-$DATE.tar.gz"
find "$BACKUP_DIR" -name "pihole-backup-*.tar.gz" -mtime +60 -deleteAutomating Pi-hole With the CLI and API
Almost everything you can do in the web dashboard has a CLI or API equivalent, which matters once you want to script Pi-hole into a larger home-lab setup, a monitoring dashboard, or a scheduled maintenance job. The pihole command handles the day-to-day administrative tasks:
# Temporarily disable blocking for 5 minutes (useful when troubleshooting a site)
pihole disable 5m
# Re-enable blocking immediately
pihole enable
# Add a domain to the whitelist from the command line
pihole allow example.com
# Tail the live query log without opening the dashboard
pihole -t
# Check for and install Pi-hole, FTL, and web interface updates
pihole -upFor programmatic access, Pi-hole v6, which launched in February 2025 and introduced an embedded web server alongside this new authenticated REST API served directly by FTL, replaced the old PHP-based API entirely, reachable at http://<pi-hole-ip>/api. It’s the same API the redesigned v6 dashboard itself uses, which means anything the web UI can show, a script can pull as JSON, including live query counts, top blocked domains, and per-client statistics. That makes it straightforward to feed Pi-hole’s stats into a home dashboard tool like Grafana or Home Assistant, rather than relying on the built-in admin page as the only place to check status.
What to Expect: Blocking Rates and Query Volume
New Pi-hole users often ask what “normal” looks like on the dashboard within the first few days. There’s no single official benchmark figure, since blocking percentage depends heavily on which lists you run, how many devices are on the network, and how ad-heavy the apps and sites those devices use actually are. That said, a few patterns show up consistently across home-lab writeups and community reporting: households running a single aggregated list like StevenBlack’s typically see a meaningfully higher blocked-query percentage in the first 24-48 hours than they do after a week, simply because smart TVs and streaming apps tend to front-load a burst of tracking and telemetry calls on first connection, then settle into a steadier baseline. Networks with more IoT devices (smart plugs, cameras, voice assistants) tend to show a higher proportion of blocked queries than a network of just laptops and phones, since consumer IoT firmware is disproportionately chatty with analytics and advertising endpoints compared to general-purpose computers.
Rather than chasing a specific blocking percentage as a goal, use the Query Log’s Top Blocked Domains widget as your real signal. If you see a legitimate service repeatedly blocked, whitelist it. If you see an unfamiliar domain generating a high query volume from a single device, that’s worth investigating directly, since it can indicate anything from an overly chatty analytics SDK bundled into an app to genuinely unwanted background telemetry you didn’t know was happening.
Maintaining Pi-hole After Setup
Pi-hole is low-maintenance once stable, but it is not zero-maintenance. Update Pi-hole itself periodically with pihole -up, which checks for and applies new Core, FTL and web interface releases in one command. Keep the underlying OS patched independently, since a lapsed Debian or Ubuntu install is a far more common security exposure than anything in Pi-hole’s own codebase; Pi-hole itself does receive security fixes too, as the Core v6.5, FTL v6.8 and Web v6.6.1 release of October 17, 2026 shows, so the host OS and the Pi-hole stack both need regular patching. Review blocklists every few months, since domains do go stale or get repurposed, and check the Query Log’s top clients view periodically to catch a device generating an unusually high query volume, which can indicate anything from a misconfigured app to malware attempting frequent command-and-control callbacks that Pi-hole is now quietly blocking and logging for you.
Security Fixes in the Core v6.5 Release
Pi-hole FTL v6.8, Web v6.6.1 and Core v6.5 are now available, and the Docker image is tagged 2026.10.0. In Core, command execution via a crafted PID (GHSA-cf36-4hhc-8398, CVSS 7.8) is fixed because getFTLPID() now only accepts a PID naming a running pihole-FTL. Core also adds /opt/pihole hardening (GHSA-j8vh-6fp9-cjcx, CVSS 7.8), making it read-only for the FTL service, and addresses root writing to config-supplied paths (GHSA-mff6-cjc4-5wq9, CVSS 7.3), since gravity.sh re-executes as pihole and the log flush writes as pihole.
On the FTL side, local file contents were echoed when parsing a file:// adlist (GHSA-667h-gpmh-7gxc, CVSS 6.5), so an authenticated user could read files the pihole user can open, and the fix needs the matching Core change. An out-of-bounds write in the API TXT buffer (GHSA-8fc6-q9x4-892v, CVSS 5.9) needs a long upstream server list and no authentication. In the web interface, stored XSS on three settings pages (Settings > All settings, Local DNS Records and DNS) was fixed, with CVSS scores of 3.5 / 3.1 / 3.1.
For readers still on the previous Core v6.4.3 stack, the practical step is to export a backup, read the changelogs and then run pihole -up. Docker users should move to the image tagged 2026.10.0 rather than assuming an old container has picked up these fixes. FTL v6.7.1 had been released by September 21, 2026, and the October fixes addressed issues users encountered with that version, so the upgrade is worth doing even if your install seems to be running normally.
Frequently Asked Questions
Does Pi-hole slow down my internet connection?
No. DNS lookups are cached after the first request, and a blocked ad domain resolves faster than a real one because Pi-hole answers locally instead of waiting on a round trip to an ad server. Most users report pages loading noticeably faster once ad and tracker requests stop being made at all.
Do I need a Raspberry Pi to run Pi-hole?
No. Pi-hole runs on any Linux host or in Docker on nearly any OS, including inside a VM on a NAS, an old laptop, or a small dedicated mini PC. The name reflects the project’s 2015 origin, not a hardware requirement.
Will Pi-hole block all ads, including on YouTube?
It blocks a large share of ad and tracker domains but cannot remove ads served from the same domain as the content itself, which is why some YouTube and app-embedded ads still get through. Browser extensions still add value on top of DNS-level blocking for that reason.
Is Pi-hole free, and is there a paid tier?
Pi-hole’s core software is free and open source. There is no official paid Pi-hole subscription tier as of this writing; donations support ongoing development, but every feature covered in this tutorial is available in the free release.
What happens if the Pi-hole host goes down?
Every device configured to use only that IP for DNS loses the ability to resolve domain names, which functionally breaks internet access even though the connection itself is fine. This is why Step 11 covers setting up a secondary Pi-hole for DHCP failover.
Should I use Unbound or just point Pi-hole at Cloudflare or Google DNS?
Pointing at a public upstream is simpler and works fine for most users. Unbound removes a third party from seeing your DNS queries at all, at the cost of a slightly more involved setup covered in Step 8. Choose based on how much you weigh that privacy trade-off against setup simplicity.
Can Pi-hole and AdGuard Home run on the same network?
Yes, and it’s a common redundancy pattern: run one as your router’s primary DNS and the other as secondary, so a failure or update on one doesn’t take down name resolution network-wide.
How do I know Pi-hole is actually working?
Open the admin dashboard’s Query Log in real time while browsing a site with known ad networks, and watch domains get marked as blocked. The dashboard’s blocking percentage and top-blocked-domains widgets update live and are the fastest way to confirm filtering is active across your devices.
