Whitelisting and blacklisting in Pi-hole aren’t about blocking ads, they’re about controlling which DNS queries Pi-hole is allowed to resolve at all.
Let’s see it in action. Imagine you want to ensure your kids can only access educational websites, and nothing else. You can achieve this with a very aggressive blacklist and a very specific whitelist.
Here’s a typical Pi-hole /etc/pihole/gravity.list file, which is what Pi-hole uses for its blocking. It’s thousands of lines long, full of ad and tracker domains:
0.0.0.0 ads.example-tracker.com
0.0.0.0 doubleclick.net
0.0.0.0 googleadservices.com
... (many more)
Now, let’s say you want to whitelist kids-educational-game.com. You’d go to your Pi-hole web interface, navigate to "Domain Management," and add kids-educational-game.com to your whitelist. Pi-hole will then add a line to its /etc/pihole/local.list file (or similar) like this:
kids-educational-game.com
When a client on your network requests kids-educational-game.com, Pi-hole checks its whitelists first. If it finds a match, it bypasses all blocklists and upstream DNS servers, and directly resolves the domain (usually to 0.0.0.0 or NXDOMAIN, depending on your Pi-hole settings, but the key is it doesn’t go out to the real internet for it).
Conversely, if you want to block unwanted-social-media.com, you add it to the blacklist. Pi-hole adds it to /etc/pihole/gravity.list (or a custom list it manages), and when a query for unwanted-social-media.com comes in, Pi-hole sees it’s on a blocklist and returns 0.0.0.0 or NXDOMAIN without querying upstream.
The core problem Pi-hole solves here is granular control over your network’s internet access at the DNS level. Instead of relying on individual device settings or complex firewall rules, Pi-hole provides a centralized, easy-to-manage system for deciding which domain names your devices are allowed to look up. It’s a powerful tool for privacy, security, and parental controls.
Internally, Pi-hole maintains several lists:
- Gravity List (
gravity.list): This is the massive, curated list of known ad and tracking domains. It’s generated by Pi-hole’sgravitytool, which downloads and merges lists from various online sources. - Wildcard Blocklist (
wildcard.list): For blocking entire subdomains (e.g., blocking*.example.commeansads.example.com,tracker.example.com, etc., are all blocked). - Blacklist (
local.listor custom lists): Domains you manually add to block. - Whitelist (
local.listor custom lists): Domains you manually add to never block, even if they appear on a gravity list.
When a DNS query arrives, Pi-hole checks the whitelist first. If it’s there, it resolves. If not, it checks the blocklists (gravity, wildcard, and manual blacklists). If it’s on any blocklist, it returns a blocked response. If it’s not on any list and not whitelisted, Pi-hole forwards the query to your configured upstream DNS server (like 1.1.1.1 or 8.8.8.8).
The most surprising thing about Pi-hole’s whitelisting is that it takes precedence over everything. You can have doubleclick.net in ten different gravity blocklists, but if you whitelist doubleclick.net, Pi-hole will happily resolve it. This is how you can selectively allow specific domains that might otherwise be blocked, often for legitimate services or specific applications.
The next logical step is to explore Pi-hole’s regex filtering, which allows for even more dynamic and pattern-based blocking and whitelisting.