How to Self-Host Pi-hole: Network-Wide Ad Blocking for Every Device on Your Network

How Pi-hole DNS filtering works

DNS translates names such as example.com into addresses that applications can contact. In a Pi-hole deployment, clients send their DNS questions to Pi-hole instead of sending them directly to an ISP or public resolver. Pi-hole evaluates each requested domain against its local rules and subscribed lists.

If a domain is allowed, Pi-hole forwards the question to the configured upstream resolver and returns the result. If it is blocked, Pi-hole answers according to its configured blocking mode. That response might be an unspecified address, an empty answer, or another policy response. It is therefore incorrect to use 0.0.0.0 as the only sign that filtering works. The Pi-hole query log and the DNS response status provide better evidence.

Normal path
Client
  |
  | DNS query
  v
Pi-hole
  |
  +-- Domain blocked? Yes --> Configured blocking response
  |
  +-- Domain blocked? No ---> Upstream resolver ---> Answer returned

Possible bypass paths
Client --> hardcoded external DNS
Client --> IPv6 DNS announced separately by the router
Application --> DNS over HTTPS or another encrypted resolver

Pi-hole works especially well for devices that cannot install a browser extension, including televisions, media players, consoles, appliances, and mobile applications. It can also provide visibility into DNS activity, subject to the logging and privacy settings you choose.

Platform and network prerequisites

For a bare-metal installation, use a Linux distribution currently supported by Pi-hole's installer. Raspberry Pi OS, Debian, and Ubuntu are common choices, but supported releases change over time. The installer performs an operating-system check, so confirm the current support matrix before upgrading the host to a newly released distribution. Do not disable the installer check to force an unsupported operating system into service.

The Docker path requires a Linux host with a supported Docker Engine and the Docker Compose plugin. The host must be able to reserve DNS port 53 over both UDP and TCP. This tutorial keeps DHCP on the router and does not enable Pi-hole's optional DHCP server. That avoids adding DHCP port exposure, extra container capabilities, and a network migration that varies significantly between routers.

Choose the address before installation

For IPv4, a DHCP reservation is usually the least disruptive option because the router continues managing the address while guaranteeing that the Pi-hole host receives the same lease. If you configure the address directly on Linux, make sure it does not overlap the router's dynamic allocation range.

IPv6 needs separate attention. A privacy or temporary IPv6 address is unsuitable as the network's permanent DNS destination. Use an address intended to remain stable on the LAN. If your ISP delegates a changing IPv6 prefix, consider how a prefix change affects the address advertised to clients. Router behavior differs, so verify the actual resolver received by clients rather than assuming the IPv4 setting also controls IPv6.

Check port conflicts and current host resolution

sudo ss -lntup | grep ':53 '
readlink -f /etc/resolv.conf
getent hosts example.com

The first command identifies any process already listening on port 53. The second shows how the host's resolver file is managed. The third confirms that name resolution works before changes are made. Save this output with your deployment notes.

Install Pi-hole directly on Raspberry Pi OS, Debian, or Ubuntu

A direct installation is appropriate when the machine is dedicated to Pi-hole or when you prefer system services over containers. Begin with an updated, currently supported operating-system release and a stable network address.

sudo mkdir -p /etc/systemd/resolved.conf.d

printf '[Resolve]\nDNSStubListener=no\n' |
  sudo tee /etc/systemd/resolved.conf.d/pihole-port-53.conf

sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

readlink -f /etc/resolv.conf
getent hosts example.com
sudo ss -lntup | grep ':53 ' || true

curl -sSL https://install.pi-hole.net | bash

dig @127.0.0.1 example.com A
dig @PIHOLE_LAN_IP example.com A

Deploy Pi-hole with Docker Compose

Docker provides a reproducible deployment and keeps Pi-hole's files in an explicit persistent mount. It does not remove the need for a stable host address, port-conflict checks, backups, or careful DNS rollout.

The official image publishes versioned tags and a mutable latest tag. A mutable tag can change the software delivered by a future pull. For repeatable production deployment, set PIHOLE_IMAGE to a release tag or immutable digest that you have checked against the current official Pi-hole Docker documentation. An exact current release is intentionally not hardcoded here because release tags change after publication.

sudo mkdir -p /opt/pihole
sudo chown "$USER":"$USER" /opt/pihole
cd /opt/pihole
mkdir -p etc-pihole

cat > .env <<'EOF'
PIHOLE_IMAGE=pihole/pihole:REPLACE_WITH_VERIFIED_RELEASE_TAG
PIHOLE_HOST_IP=192.168.1.10
PIHOLE_WEB_PASSWORD=REPLACE_WITH_A_LONG_UNIQUE_PASSWORD
TZ=Etc/UTC
EOF

chmod 600 .env

services:
  pihole:
    container_name: pihole
    image: ${PIHOLE_IMAGE}
    restart: unless-stopped
    ports:
      - "${PIHOLE_HOST_IP}:53:53/tcp"
      - "${PIHOLE_HOST_IP}:53:53/udp"
      - "${PIHOLE_HOST_IP}:8080:80/tcp"
    environment:
      TZ: "${TZ}"
      FTLCONF_webserver_api_password: "${PIHOLE_WEB_PASSWORD}"
      FTLCONF_dns_listeningMode: "ALL"
    volumes:
      - "./etc-pihole:/etc/pihole"

sudo ss -lntup | grep ':53 ' || true
sudo ss -lntup | grep ':8080 ' || true
docker compose config

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 pihole

dig @PIHOLE_HOST_IP example.com A

Point your network to Pi-hole safely

The router normally remains the DHCP server in this tutorial. Its job is to give clients an address, gateway, lease duration, and DNS configuration. Router interfaces differ, so look for LAN DHCP, local network, DNS server, and IPv6 router-advertisement settings rather than relying on a universal menu path.

Start with one test client

Before changing DHCP, manually set one computer's DNS server to Pi-hole's stable IPv4 address. If the network uses IPv6, configure the Pi-hole IPv6 address as well. Disconnect and reconnect the test client, clear its DNS cache if necessary, and complete the verification steps in the next section.

Advertise Pi-hole through router DHCP

After the test client succeeds, enter Pi-hole's IPv4 address as the LAN DNS server distributed by DHCP. Save the change, then renew leases or reconnect clients. Existing devices may keep the old DNS information until their leases are renewed, so a router change does not necessarily affect every device immediately.

A secondary DNS field is not consistently treated as standby-only. Many operating systems can query either resolver based on timing and internal selection logic. If you enter a public resolver as secondary DNS, some traffic can bypass Pi-hole even while Pi-hole is healthy.

For redundancy, the better design is usually a second independently hosted Pi-hole with the same policy. Advertise both Pi-hole addresses and monitor both systems. Two addresses on the same physical host do not protect against host failure.

Configure IPv6 separately

Inspect the router's IPv6 DNS and router-advertisement settings. If the router continues advertising an ISP or public IPv6 resolver, capable clients can use it instead of the IPv4 Pi-hole address. Advertise Pi-hole's stable IPv6 address where the router supports it, then verify the resolver on an IPv6-enabled client.

Some routers advertise themselves as the DNS server and forward queries internally. In that design, Pi-hole may see the router as the client instead of seeing individual devices. This can still filter traffic, but per-device reporting may be less useful. Whether the router can advertise Pi-hole directly depends on its firmware.

Handle guest networks and VLANs deliberately

Guest Wi-Fi and VLANs often use separate DHCP scopes and firewall rules. Configure DNS independently for each segment that should use Pi-hole. Permit DNS from those clients to Pi-hole over TCP and UDP port 53, but do not open unrelated access to the Pi-hole host. If a segment should remain isolated, keep its firewall policy intact and add only the required DNS path.

Verify server-side, client-side, IPv4, and IPv6 DNS

A dashboard showing queries is useful, but deployment verification should prove each part of the path. Test ordinary resolution first, then a controlled blocking rule, and finally inspect what resolver each client actually uses.

1. Test Pi-hole directly over IPv4

dig @PIHOLE_IPV4_ADDRESS example.com A
dig @PIHOLE_IPV4_ADDRESS example.com AAAA

In the output, confirm that the responding server is the Pi-hole IPv4 address. A valid answer proves that Pi-hole can receive the query and reach its upstream resolver. It does not yet prove that the client uses Pi-hole by default.

2. Create a controlled blocking test

In the Pi-hole administration interface, add an exact deny rule for a deliberately unused test name such as pihole-test.invalid. Query it directly:

dig @PIHOLE_IPV4_ADDRESS pihole-test.invalid A

Confirm in Pi-hole's query log that the request was blocked by the exact local rule. Do not require a specific returned address because the answer depends on the configured blocking mode. Remove the temporary rule after the test.

3. Test the client's default resolver

nslookup example.com
nslookup pihole-test.invalid

The resolver displayed by nslookup should be Pi-hole or, in a router-forwarding design, the expected router address. Confirm the requests appear in Pi-hole's query log. If direct queries work but default client queries do not appear, the problem is DHCP, router advertisement, manual client settings, a VPN, or application-specific DNS.

4. Test IPv6 explicitly

dig -6 @PIHOLE_IPV6_ADDRESS example.com AAAA
dig -6 @PIHOLE_IPV6_ADDRESS pihole-test.invalid A

Then inspect the client's active network configuration for every assigned DNS server. The command is operating-system specific, but the goal is the same: make sure an unexpected ISP or public IPv6 resolver is not present.

5. Test after lease renewal and reconnection

Renew the client's DHCP lease or disconnect and reconnect it. Repeat the default-resolver test. Also test a phone, television, or other device class important to your network. A result from one computer does not prove that every VLAN, wireless network, and device follows the same path.

Choose blocklists and allow rules conservatively

A larger blocked-domain count is not a useful goal by itself. Overlapping lists increase processing and troubleshooting work while aggressive lists can break authentication, payments, media playback, referral links, and application APIs. Begin with one general-purpose list, observe the network, and add a specialized list only for a defined need.

HaGeZi publishes several output formats. Use the format identified for Pi-hole or ad-blocking applications, not an RPZ, wildcard, or DNSMasq-specific variant chosen at random. The project currently directs new users to one Multi PRO list plus the optional Threat Intelligence Feeds list. Entry counts change frequently and should not be treated as fixed product specifications.

StevenBlack's project consolidates multiple curated sources and removes duplicates. Its category variants are alternatives built for different policies. A household content policy and a malware-domain policy are different requirements, so document why each category is enabled.

OISD, URLHaus, and similar projects can change formats, mirrors, and inclusion policies. Obtain their current Pi-hole-compatible URLs from the primary project at configuration time. This avoids publishing a stale mirror or adding an incompatible list.

Diagnose false positives before allowing a domain

Updates, backups, restores, and routine operation

Update a bare-metal installation

Create a Teleporter export and read the release notes before updating. On a supported bare-metal installation, Pi-hole's own update command is:

pihole -up

Run it on the Pi-hole host with appropriate privileges. Afterward, repeat direct IPv4, direct IPv6, client-default, and controlled-blocking tests.

Update a Docker deployment

Do not run pihole -up inside the container. Container updates are performed by selecting a newer image, pulling it, and recreating the container while retaining the persistent /etc/pihole mount.

cd /opt/pihole

# First update PIHOLE_IMAGE in .env to the reviewed release tag or digest.
docker compose pull
docker compose up -d

docker compose ps
docker compose logs --tail=100 pihole

Keep the previous image reference in your change record so rollback is possible if the new release and migrated data remain compatible with the documented rollback procedure. Never assume that changing a tag backward is a safe database rollback.

Understand Pi-hole's databases

gravity.db is the filtering and list database. It is not the query-history database. Query history is managed separately by Pi-hole FTL. Treat all SQLite databases as live application data and avoid copying them while writes are in progress unless the application provides a consistent export mechanism.

Preferred backup: Teleporter

Use the Teleporter function in the Pi-hole administration interface to export supported configuration data. Store the resulting archive outside the Pi-hole host, protect it according to the sensitivity of your local DNS and policy information, and record the Pi-hole version that produced it.

A Teleporter archive is not equivalent to copying /etc/pihole. Teleporter is an application-aware configuration export. A raw directory backup can include live databases, runtime files, permissions, and version-specific state.

Consistent Docker volume backup

If you need a filesystem-level Docker backup, stop the container before archiving its bind mount:

cd /opt/pihole
docker compose stop pihole

sudo tar --numeric-owner -czf \
  "/secure-backup-location/pihole-files-$(date +%Y%m%d).tar.gz" \
  etc-pihole .env compose.yaml

docker compose start pihole

Protect this archive because it can contain configuration and sensitive operational data. Use the actual Compose filename if it differs from compose.yaml.

Restore and test

For a normal migration, install a compatible Pi-hole version, open its Teleporter function, import the archive, restart as instructed by that version, and verify upstream DNS, local rules, subscribed lists, privacy settings, and client resolution.

For a filesystem-level Docker restore, stop the container, preserve the failed directory separately, extract the archive to the original path, verify ownership and permissions, and start the same reviewed image version. Do not overlay a raw backup on a running container.

A backup is not proven until it has been restored. Test restoration on an isolated host or isolated Docker project that does not bind the production address or port 53. Confirm that the administration interface loads, expected lists and local rules exist, and direct DNS tests succeed. Record the result and the date.

Routine maintenance checklist

• Confirm that the host address and router-advertised DNS values have not changed.
• Monitor storage health, container or service status, and failed list downloads.
• Review unusual query volume without assuming every busy client is malicious.
• Remove unused blocklists and stale allow rules.
• Check that backups exist outside the host and periodically test a restore.
• Review release notes before host, Pi-hole, Docker, or router upgrades.
• Repeat IPv4 and IPv6 verification after network changes.

Access the Pi-hole administration interface remotely

DNS service and web administration are separate traffic paths. LAN clients should continue sending DNS to Pi-hole locally on TCP and UDP port 53. If remote administration is required, expose only the web interface through an HTTP tunnel. Do not publish the DNS service through an HTTP tunnel.

LAN DNS path
LAN clients -- TCP/UDP 53 --> Pi-hole --> Upstream resolver

Remote administration path
Remote browser -- HTTPS --> Localtonet relay
                                  ^
                                  |
                         outbound tunnel connection
                                  |
                       Localtonet client on host
                                  |
                       Pi-hole web administration

Port 53 remains on the private LAN.

With Localtonet, the client on your device establishes an outbound connection to one of our relay servers. This avoids inbound router port forwarding, firewall changes, VPN setup, and the need for a public IP address. The tunnel is available only while the selected client is connected and the tunnel is running.

If public administration is unnecessary, private network access is safer. A private mesh can restrict the interface to authenticated devices without publishing it as a public website. Localtonet VPN Manager provides a private mesh VPN with granular firewall rules and can bridge local LANs. Standard HTTP, TCP, UDP, and File Server tunnels are not VPN functionality, so choose VPN Manager specifically when private network access is the goal.

Evidence-based troubleshooting

Recover from a DNS outage

If a network-wide change prevents name resolution, use an IP address to reach the router and Pi-hole host. Restore the router's previous DHCP DNS values, renew a test client's lease, and confirm ordinary resolution. Then diagnose Pi-hole through direct IP access. Avoid making several unrelated changes at once because doing so hides the original cause.

Distinguish DNS failure from internet failure

If a client can reach a known local IP address but cannot resolve a hostname, investigate DNS. If it cannot reach the gateway or other local addresses, the problem is broader than Pi-hole. A direct query to Pi-hole separates server reachability from the client's default resolver selection:

dig @PIHOLE_IPV4_ADDRESS example.com A

If this direct query succeeds while an ordinary nslookup example.com fails or uses another resolver, focus on DHCP, IPv6 advertisement, VPN, or client configuration rather than changing Pi-hole's filtering settings.

Frequently asked questions