Pi-hole is a network-wide DNS sinkhole that intercepts ad and tracker requests before they reach your devices, blocking them silently at the DNS layer for every client on your home network, no browser extension required.
Running a proper pihole setup means every phone, smart TV, laptop, and IoT sensor on your network gets ad and tracker blocking automatically. There is nothing to install on individual devices.
For data hoarders and home lab enthusiasts, Pi-hole adds a layer of network-level privacy that pairs naturally with a NAS, a VPN, and tools like Unbound for recursive DNS resolution. The combination of Pi-hole and a VPN with secure upstream DNS is one of the most effective ways to prevent DNS leaks while keeping your entire network clean.
This guide walks through deploying Pi-hole in Docker on a NAS, routing your network through it safely, configuring upstream DNS, and keeping it running without issues over the long term.
What Pi-hole Does on a Home Network
Pi-hole replaces your router’s default DNS resolver and intercepts every domain lookup made by devices on your network. It checks each query against blocklists and drops requests to known ad servers, trackers, and telemetry endpoints before a connection is ever made. What gets through resolves normally; what matches a blocked domain returns nothing.
How Pi-hole Works as a DNS Server
Every device that connects to the internet translates domain names into IP addresses through DNS. Normally, your router forwards those queries to a public DNS provider like 8.8.8.8 or your ISP’s servers.
Pi-hole intercepts that process. It becomes the DNS server your router points clients to, and it filters queries using blocklists loaded into a local database. Blocked domains return a null response. Allowed domains get forwarded to whatever upstream DNS server you configure.
The query log in the Pi-hole admin console shows every lookup in real time, including blocked domains, top blocked domains, and which client made each request.
What Pi-hole Blocks and What It Cannot Block
Pi-hole blocks DNS-based ad delivery, tracker domains, telemetry endpoints, and malware domains listed in its blocklists. This covers most advertising networks, analytics platforms, and the background data collection that smart TVs and mobile apps send constantly.
It cannot block ads that are served from the same domain as the content itself. YouTube ads, for example, come from Google’s own infrastructure, so Pi-hole cannot reliably strip them without breaking the service. First-party ad delivery is a known limitation of any DNS-based filter.
Pi-hole also does not inspect traffic or decrypt HTTPS. It works purely at the domain resolution level.
Why Pi-hole Matters for Privacy and Data Hoarding
For anyone running a NAS full of archival data, public domain archives, or large datasets, the devices on the same network are constantly phoning home. Smart TVs report viewing behavior. IoT sensors ping manufacturer servers. Even operating systems send telemetry on a schedule.
Pi-hole cuts off those connections at the DNS layer without requiring any configuration changes on individual devices. Combined with query logging and privacy modes, you get a full picture of what your network is doing and the ability to silence it selectively.
Plan Your Deployment Before You Install Pi-hole
Before writing a single line of Docker Compose, two decisions matter most: where Pi-hole will run and how your network will route DNS traffic to it. Getting those right upfront avoids the most common problems.
Native Install vs Docker on a NAS
The native install method uses the official install script at install.pi-hole.net. It runs a curl command that downloads and executes the installer directly on a Linux host. This works well on a dedicated Raspberry Pi or a bare-metal Ubuntu server.
Docker and Docker Compose are the better choice for a NAS. A NAS already runs 24/7, has RAID or redundant storage, and usually has Docker or Container Manager available. Pi-hole runs in its own isolated container, restarts automatically, and does not interfere with the host OS or other containers.
The trade-off with Docker on a NAS is networking. Port 53 conflicts are common because some NAS operating systems run their own DNS or DHCP services. Planning the container network before deployment saves considerable troubleshooting time.
Hardware and Network Requirements
Pi-hole is lightweight. A Raspberry Pi Zero 2 W handles a typical home network without strain. A Raspberry Pi 4 has more headroom and makes a solid dedicated host. On a NAS, Pi-hole shares resources with other containers and requires only a fraction of available RAM and CPU.
Key requirements:
- A Linux host (bare metal, VM, LXC, or Docker container)
- A static IP or DHCP reservation for the host
- Port 53 available (TCP and UDP) for DNS
- Docker and Docker Compose installed if using the container method
- A microSD card rated for sustained writes if using a Raspberry Pi (SD card endurance matters for long-running Pi-hole deployments)
Static IP and DHCP Reservation Basics
Pi-hole must have a stable IP address. If the IP changes, every device on the network that was pointed at it loses DNS resolution.
There are two ways to handle this. The first is a DHCP reservation on the router, which ties the Pi-hole host’s MAC address to a specific IP so the DHCP server always assigns the same address. The second is configuring a static IP directly on the host or container.
For Docker deployments using macvlan networking, assigning a static IP inside the Docker Compose file is the standard approach. The container gets its own IP on the LAN, separate from the NAS host IP, which avoids port 53 conflicts cleanly.
Pi-hole Setup in Docker on a NAS
Deploying Pi-hole via Docker Compose on a NAS involves three steps: preparing the container network, writing and launching the Compose file, and completing configuration through the pi-hole admin console. The process is repeatable and easy to document for future rebuilds.
Prepare the NAS and Container Network
Before writing the Compose file, create a dedicated folder for Pi-hole’s persistent data. On a Synology NAS, a path like /volume1/docker/pihole works well. This folder will store Pi-hole’s configuration, blocklists, and the pihole-ftl database.
The bigger decision is networking mode. Two options work well in Docker:
- Host networking: Pi-hole shares the NAS host’s IP and network stack. Simple to configure but can conflict with services already using port 53 on the NAS.
- Macvlan networking: Pi-hole gets its own dedicated IP address on the LAN. This avoids all port conflicts and is the recommended approach for Synology and similar NAS platforms.
For macvlan, define a custom Docker network in your Compose file that maps to the physical LAN interface. Assign Pi-hole a static IP within your subnet that is outside the router’s DHCP pool to prevent address conflicts.
Deploy Pi-hole with Docker Compose
A minimal working Docker Compose file for Pi-hole v6 looks like this:
version: "3"
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
restart: unless-stopped
environment:
TZ: "America/New_York"
WEBPASSWORD: "your_secure_password_here"
PIHOLE_DNS_: "127.0.0.1#5335"
volumes:
- /volume1/docker/pihole/etc-pihole:/etc/pihole
- /volume1/docker/pihole/etc-dnsmasq.d:/etc/dnsmasq.d
networks:
pihole_net:
ipv4_address: 192.168.1.53
networks:
pihole_net:
driver: macvlan
driver_opts:
parent: eth0
ipam:
config:
- subnet: 192.168.1.0/24
gateway: 192.168.1.1
ip_range: 192.168.1.53/32
Adjust the subnet, gateway, and IP to match your network. The PIHOLE_DNS_ line pointing to 127.0.0.1#5335 is for Unbound, covered in a later section. For a basic setup without Unbound, replace it with a public DNS provider like 9.9.9.9 or 8.8.8.8.
Run docker compose up -d from the folder containing the Compose file to start the container.
Open the Pi-hole Admin Console and Finish Setup
Once the container is running, access the pi-hole web interface by navigating to http://192.168.1.53/admin (replace with your assigned IP). Log in with the password set in the WEBPASSWORD environment variable.
The pi-hole dashboard shows query statistics, top blocked domains, and client activity from the moment DNS traffic starts flowing through it. Before routing your full network through Pi-hole, confirm the container is healthy by running:
docker exec pihole pihole status
Inside the pi-hole admin console, review the pi-hole configuration under Settings. Confirm the upstream DNS, check that query logging is enabled, and verify that the default blocklists are loaded under Group Management. Pi-hole core comes with a default blocklist active out of the box.
Route Your Network Through Pi-hole Safely
Getting Pi-hole installed is only half the work. Routing your network through it correctly determines whether every device benefits or just the ones you configure manually. The safest approach involves changing one setting on the router and keeping a fallback plan in place.
Change Router DHCP Settings the Right Way
The cleanest way to force all network clients through Pi-hole is to update the router’s DHCP settings. Most routers have a field labeled “Primary DNS Server” in the DHCP configuration section. Set that to Pi-hole’s static IP.
Do not disable the DHCP server on the router unless you are specifically enabling Pi-hole’s built-in DHCP server as a replacement. Changing only the DNS field in DHCP settings is the minimal, lower-risk approach.
After saving, devices will receive Pi-hole’s IP as their DNS server the next time they renew a DHCP lease. You can speed this up by reconnecting devices or running ipconfig /renew on Windows clients.
Use Pi-hole as Primary DNS With a Fallback Plan
Setting Pi-hole as the only DNS server means that if the container stops, the entire network loses DNS resolution. Everything appears to go offline even though the internet connection itself is fine.
Two mitigations work well:
- Set a secondary DNS server in the router’s DHCP settings, pointing to a reliable public DNS like
9.9.9.9. Clients will fall back to this if Pi-hole is unreachable. The trade-off is that failed Pi-hole requests bypass filtering temporarily. - Set the container restart policy to
unless-stoppedin Docker Compose, so Pi-hole restarts automatically after a NAS reboot or container crash.
For Home Assistant users or anyone running other home lab services, confirm that those services resolve DNS correctly after pointing them at Pi-hole. Some containers have hardcoded DNS settings that override DHCP.
Test Clients and Confirm Queries Are Reaching Pi-hole
After updating DHCP settings, open the pi-hole dashboard and watch the query log in real time. Browse a few websites from a phone or laptop and confirm queries appear in the log. If nothing shows up, the client is likely still using its old DNS from a cached DHCP lease.
Run nslookup pi.hole from a client device. If it resolves correctly, that device is using Pi-hole. The query log will also show a corresponding entry.
Check pihole status from the dashboard or by running docker exec pihole pihole status to confirm the DNS service is active and responding.
Choose Upstream DNS, Unbound, and VPN Settings
Pi-hole itself does not resolve DNS from scratch. It forwards queries it does not block to an upstream DNS provider or a local recursive resolver. Choosing the right upstream is where privacy and DNS leak prevention become critical, especially when a VPN is active on the network.
When to Use Public DNS Providers
Public DNS providers like Quad9 (9.9.9.9), Google (8.8.8.8 and 8.8.4.4), and OpenDNS are easy to configure and reliable. Pi-hole supports them out of the box with preset options during initial setup.
The privacy concern with public DNS is that your upstream resolver sees every domain query your network makes, even if Pi-hole handles the filtering layer. If you are routing traffic through a VPN, your queries should ideally go to a DNS server that does not log them or correlate them with your identity.
If your VPN provider offers their own secure DNS servers, configure Pi-hole to use those as its upstream. For example, a provider like PrivadoVPN publishes DNS server addresses specifically for use with their service. Setting those as Pi-hole’s upstream DNS ensures that queries leaving Pi-hole travel through the VPN’s DNS infrastructure rather than a public resolver, preventing DNS leaks at the network level.
See our best VPN for Usenet picks for providers that publish their own secure DNS servers.
Install Unbound for Recursive DNS
Unbound is a recursive DNS resolver that queries the DNS root servers directly, without sending your lookups to any third-party provider. Pairing it with Pi-hole means Pi-hole handles filtering and Unbound handles resolution, with no external DNS provider in the chain.
The most portable way to run Unbound alongside Pi-hole in Docker is using the mvance/unbound image. Add it as a second service in the same Docker Compose file:
unbound:
container_name: unbound
image: mvance/unbound:latest
restart: unless-stopped
networks:
pihole_net:
ipv4_address: 192.168.1.54
Configure Pi-hole’s upstream DNS to point to Unbound’s container IP on port 5335 (the default for the mvance image). In the Compose environment for Pi-hole, set:
PIHOLE_DNS_: "192.168.1.54#5335"
Unbound supports DNSSEC validation and encrypted DNS, which adds another layer of integrity checking to every resolved query. To test DNSSEC is working, run:
dig sigfail.verteiltesysteme.net @192.168.1.54 -p 5335
A SERVFAIL response confirms DNSSEC is validating correctly.
Prevent DNS Leaks When a VPN Is Active
A DNS leak happens when your VPN tunnels your web traffic but your DNS queries still travel outside the tunnel to an unprotected resolver. This exposes your browsing activity to your ISP or the public resolver even though your IP appears hidden.
When Pi-hole is your network’s DNS server and it forwards queries to a public resolver like 8.8.8.8 outside the VPN tunnel, those queries leak. The fix is routing Pi-hole’s upstream DNS traffic through the VPN.
Practical options:
- VPN provider DNS as upstream: Set Pi-hole to use your VPN provider‘s DNS server IP. If the VPN is active on the router, those queries travel through the tunnel automatically.
- Tailscale integration: Tailscale can be deployed as a container alongside Pi-hole. Configure Tailscale to use Pi-hole as its DNS resolver, so devices connected via Tailscale also get filtering and DNS leak protection regardless of their physical location.
- Unbound with DNS-over-TLS: Configure Unbound to use a privacy-respecting upstream with encrypted DNS for the final resolution hop, reducing exposure even if the VPN drops temporarily.
The key principle is that Pi-hole’s upstream DNS server should always be reachable through the VPN tunnel, not around it.
Tuning, Maintenance, and Troubleshooting
Once Pi-hole is running and routing DNS correctly, the ongoing work is mostly about blocklist quality, staying current with updates, and diagnosing the occasional breakage. Most issues have straightforward causes once you know where to look.
Manage Blocklists, Allowlists, and Privacy Modes
Pi-hole’s default blocklist covers a broad range of ad and tracker domains, but adding curated custom blocklists significantly improves coverage. Firebog.net maintains a well-organized collection of blocklists organized by category and aggressiveness. The Hagezi Multi Pro list is a popular choice for comprehensive tracker blocking without excessive false positives.
Add blocklists through the Pi-hole admin console under Group Management. After adding new list URLs, run pihole -g (or use the “Update Gravity” button in the web interface) to download and compile the new domains into the gravity database.
The allowlist is equally important. When a legitimate service breaks after Pi-hole starts filtering, the query log identifies the blocked domain immediately. Add that domain to the allowlist through the console to restore it.
Privacy modes control how much query data Pi-hole stores and displays. If query logging feels intrusive, Pi-hole v6 offers several privacy levels that anonymize or reduce the data retained, without disabling filtering.
Update Gravity and Keep Pi-hole Current
Blocklist data goes stale. Running pihole -g refreshes the gravity database with the latest entries from all configured blocklist sources. Automating this with a cron job keeps coverage current without manual intervention.
A simple weekly gravity update cron entry on the host:
0 3 * * 0 docker exec pihole pihole -g
To update Pi-hole itself, run pihole -up inside the container or pull the latest image and recreate the container:
docker compose pull && docker compose up -d
Use pihole -c for a real-time statistics summary in the terminal. Use pihole -t to tail the Pi-hole log directly, which is useful for diagnosing live issues.
Fix Common Issues With DNS, Docker, and Client Devices
The most common problem after initial setup is clients not using Pi-hole despite DHCP changes. This is almost always a caching issue. Force a DHCP lease renewal on the device, or manually set the DNS server in the device’s network settings to Pi-hole’s IP to confirm it works.
Port 53 conflicts are the second most common Docker issue. If the container fails to start with a bind error on port 53, another service on the host is using that port. On Synology NAS, the built-in DNS server or Synology’s own DNS relay can conflict. Disabling those services or switching to macvlan networking resolves it.
If Pi-hole is running but pages are broken or services time out, check the query log for NXDOMAIN responses. A legitimate domain caught in a blocklist is the likely cause. The allowlist fixes this in seconds.
For AdGuard Home users considering a switch, the workflow is similar. The main structural difference is that AdGuard Home uses a different configuration format and has a slightly different approach to upstream DNS, but the networking principles carry over directly.
Frequently Asked Questions
How do I install and configure an ad-blocking DNS server on a Raspberry Pi?
curl -sSL https://install.pi-hole.net | bash. The interactive installer walks through upstream DNS selection, static IP confirmation, and web interface setup. After installation, point your router’s DHCP DNS setting to the Pi’s IP address.What are the hardware and OS requirements for running a network-wide DNS ad blocker at home?
How do I set it up to work with my router so all devices use it automatically?
Why aren’t ads being blocked, and how can I troubleshoot DNS and client settings?
nslookup pi.hole from the device to confirm it resolves. If queries appear but ads still show, those ads are likely served from first-party domains that Pi-hole cannot block.