What is Pi-hole: ad blocking for your whole network, in simple terms

Pi-hole is a DNS server with filtering that blocks ads and trackers for all devices on the network at once: computers, phones, TVs, and smart devices where you can’t install a browser extension. Pi-hole is installed on a small computer or a virtual machine in the local network and set as the DNS server in the router. After that, requests to ad and tracking domains receive an empty response, and other requests are handled as usual.

Pi-hole is an open project; you can run it on a Raspberry Pi, on a virtual machine, or in a Docker container.

How it works

Before opening a website or loading an ad banner, a device asks a DNS server for the domain’s IP address. If the DNS server is Pi-hole, it:

1. Compares the domain against blocklists.
2. If the domain is found in a list — returns an “empty” response, and the device cannot load the ad or send data to the tracker.
3. If the domain is not in the lists — forwards the request to an upstream DNS server and caches the response.

The Pi-hole web interface shows which devices request which domains, how many requests are blocked, and allows manually allowing or blocking domains.

What changed in Pi-hole v6

In February 2025 the sixth version was released, which noticeably simplified Pi-hole’s setup:

• Built-in web server and REST API are now inside pihole-FTL. Separate lighttpd and PHP are no longer required.
• Settings are gathered in a single file /etc/pihole/pihole.toml with detailed comments. Configuration from version 5 is migrated automatically.
• Allowlist subscriptions work the same as blocklist subscriptions, only they allow domains.
• HTTPS for the web interface — with your own certificate or with one created automatically.
• The Docker image is built on Alpine and has become significantly smaller.
• The web interface has been redesigned: settings are split into basic and expert modes.

If you read guides for older versions that mention lighttpd, setupVars.conf and PHP — they no longer apply to v6.

Installation

You need a device running Linux in the local network, available 24/7, with a fixed IP address: either static or reserved for it in the router’s DHCP.

The official installation method is a one-liner:

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

Pi-hole documentation itself warns that piping the script to | bash does not let you read the code before execution. It’s safer to download the script, inspect it, and run it separately:

wget -O basic-install.sh https://install.pi-hole.net
less basic-install.sh
sudo bash basic-install.sh

The installer will ask for an upstream DNS server, the network interface, and initial blocklists, and at the end will show the web interface password. There is an official Docker image — how to run it is described in the Docker section of the Pi-hole documentation.

How to route your network through Pi-hole

To have filtering work for all devices without manual configuration, set the Pi-hole address as the DNS server that DHCP gives to clients in the router. If the router does not allow changing the DNS for clients, there are two options: enable Pi-hole’s DHCP server after disabling DHCP in the router, or configure DNS manually on each device.

After setup, check:

• IPv6. If the ISP and router provide devices with IPv6, the router may also give out its own IPv6 DNS address. Then some requests will bypass Pi-hole. In the router’s IPv6 settings you should either specify the Pi-hole address or disable advertising its own DNS.
• Secondary DNS. If you set a public resolver as the second DNS server, devices will periodically query it and bypass filtering. It’s more reliable to run a second Pi-hole instance.
• DNS inside apps and browsers. Browsers and apps with DNS-over-HTTPS enabled contact their own servers directly, and Pi-hole does not see those requests.

If you have a Keenetic router in the network, its DNS and filtering capabilities are described in the article Keenetic: Part 1 — Router with modular KeeneticOS.

Upstream DNS servers

Pi-hole forwards unblocked requests to a chosen resolver. Options:

• A public resolver from your ISP or a major service — the simplest option.
• Your own recursive resolver Unbound on the same machine. The official Pi-hole guide configures Unbound on port 5335, and Pi-hole is set to the custom DNS server 127.0.0.1#5335. Then requests do not go through a third-party DNS service.
• Encrypted DNS (DoH, DoT) to an upstream server. Pi-hole does not support this natively — you need an additional proxy program that accepts plain DNS queries locally and sends them over an encrypted channel.

Limitations

• Pi-hole blocks domains, not page content. Ads that come from the same domain as the main content, for example in videos on major platforms, are not blocked this way.
• Sometimes blocklists affect legitimate sites. Such domains are added to the allowlist manually or via an allowlist subscription.
• If the Pi-hole device turns off, clients will be left without DNS. For an office or a family with many devices, it’s worth running two instances.
• Blocklists and the program itself require updates: pihole -up updates Pi-hole, pihole -g updates blocklists.

Pi-hole or AdGuard Home

The closest alternative is AdGuard Home (GPLv3). Compared to Pi-hole it can work with encrypted upstream servers (DoH, DoT, DNSCrypt) out of the box and can itself act as a DoH/DoT server for clients. It also has a built-in DHCP server and parental controls. Pi-hole attracts users with transparent logs, a large community, and familiarity for those who already use it. Both are suitable for a home network; if you need encrypted DNS without additional programs, AdGuard Home is easier to start with.

Common mistakes

• No fixed IP address. The Pi-hole address changes and the network loses DNS.
• Public DNS as the secondary server in the router. Some requests bypass the filter, making it seem like Pi-hole “doesn’t work”.
• Forgotten IPv6. Devices receive the router’s DNS via IPv6.
• Pi-hole web interface accessible from the Internet. The interface and DNS server should be accessible only from the local network or via VPN.
• Too many blocklists. More lists — more false positives. Start with the default set and add lists as needed.

Summary

Pi-hole is a simple way to remove ads and trackers from all network devices at once and to see which devices contact which domains. It requires a device that stays on all the time, correct DNS configuration in the router with IPv6 in mind, and understanding that filtering works at the domain level.

Links

• Official Pi-hole website
• Pi-hole v6 announcement
• Pi-hole documentation
• Pi-hole and Unbound
• AdGuard Home