Pi-hole works by answering DNS queries with the IP address of its own web interface—or 0.0.0.0—for domains on its blocklists. When a device asks “where is tracker.example.com?” Pi-hole replies “that’s me” or “nowhere.” The browser gets nothing back, the ad never loads, and the page renders faster.

The problem starts when a domain you actually need lands on one of those lists. Maybe it is a shipping carrier’s tracking page, a link from a promotional email, or a CDN that a banking site requires for its JavaScript to load. Suddenly a site you use every day is broken, and the fix is not obvious because the page just spins or shows a blank div where content should be.

This article covers three ways to override Pi-hole’s blocking, in increasing order of power and danger. You will learn when a simple whitelist entry is enough, why wildcards solve the subdomain explosion problem, and how regex can match patterns that neither exact entries nor wildcards can reach—along with the one mistake that makes a regex rule silently fail.

The mental model: how Pi-hole decides to block or allow

Before adding rules, it helps to know the order Pi-hole uses when it receives a DNS query. The decision is not a vote. It is a strict chain of priority, and the first match wins.

  1. Exact whitelist match. If the queried domain appears in the whitelist exactly as typed, Pi-hole forwards the real IP immediately. No further checks.
  2. Exact blacklist (blocklist) match. If the domain is on a blocklist and has not been whitelisted, Pi-hole returns its blocking IP.
  3. Regex whitelist match. If no exact match exists, Pi-hole evaluates regex whitelist entries. A regex match here permits the domain.
  4. Regex blacklist match. If no whitelist regex matched, Pi-hole checks regex blacklist entries. A match blocks the domain.
  5. Wildcard blacklist. If the domain matches a wildcard entry, it is blocked. (There is no wildcard whitelist in the standard interface—wildcards are blacklist-only.)
  6. Gravity blocklists. Finally, Pi-hole checks the compiled domain lists from its gravity database.

The practical takeaway: an exact whitelist entry beats everything below it. A regex whitelist beats regex blacklists and wildcards. And a wildcard blacklist entry will block a domain and all its subdomains unless something higher-priority says otherwise.

This order explains why some “I added it to the whitelist” complaints are not actually whitelist problems at all—they are regex or wildcard issues further down the chain. I will point out where each method sits in this hierarchy as we go.

Step 1: Check the query log first

Before you add any rule, open the Pi-hole admin interface and go to Query Log. Type the domain you suspect is being blocked into the search box. The log shows every DNS query Pi-hole has seen, the client that made it, and the status: OK (allowed), Blocked (gravity), Blocked (regex), or Blocked (wildcard).

Look for the exact domain that is failing. A page at www.example.com might load its main content from www.example.com but pull tracking scripts from pixel.example.com. If the main domain shows OK in the query log but the page is broken, the problem is a subdomain or a third-party domain that the page depends on. The query log will show it as blocked.

Also note the client IP. If you have multiple VLANs or subnets and one device works while another does not, you may have group-based blocking configured. Pi-hole can apply different blocklists to different clients. The query log shows which client made the request, so you can confirm the rule you are about to add applies to the right group.

Once you have identified the exact blocked domain, you know what needs an override. The method you choose depends on how broadly that domain and its relatives need to be unblocked.

Exact whitelisting: the safest override

An exact whitelist entry tells Pi-hole “for this one fully qualified domain name, return the real IP address no matter what any blocklist says.” It sits at the top of the priority chain.

When to use it: You know the specific subdomain that is blocked, and you do not need to unblock its siblings or parent. Example: links.shippingcarrier.com is blocked and you need click-through tracking to work, but you do not want to unblock tracking.shippingcarrier.com or ads.shippingcarrier.com.

How to add it: - In the Pi-hole admin interface, go to Whitelist. - Enter the exact domain: links.shippingcarrier.com - Click Add.

That is it. The change takes effect immediately for new queries. Devices that have the old blocked answer cached locally will hold onto it until their DNS cache expires, which is typically 5–15 minutes for most operating systems. You can flush the local cache on your test machine if you want instant confirmation.

What it does not do: An exact whitelist for links.shippingcarrier.com does not whitelist www.shippingcarrier.com or shippingcarrier.com. Those are separate FQDNs. If the bare domain is also blocked, you need a second exact entry—or a different method.

Common beginner mistake: Whitelisting shippingcarrier.com and expecting it to cover www.shippingcarrier.com. DNS treats these as two distinct names. The whitelist matches character-for-character. If the blocked query is for www.shippingcarrier.com, an entry for shippingcarrier.com will not match it.

Wildcards: when one domain brings a hundred subdomains

Some services use dynamically generated subdomains. A content delivery network might serve assets from a1234.cdn.example.com, b5678.cdn.example.com, and a dozen other hostnames that change by the hour. You cannot whitelist them individually because you cannot predict the names.

Pi-hole’s wildcard feature solves this. A wildcard entry matches the domain you specify and every possible subdomain under it.

Important: Wildcards in Pi-hole are a blacklist feature. You add them on the Domains page or via the --wild flag in pihole commands. They are not added to the whitelist. When you add a wildcard entry for a domain that is currently blocked, you are effectively creating a blacklist exception by using a regex whitelist (which I will cover next) or by removing the domain from the blocklist entirely. The wildcard mechanism itself only blocks.

This trips up new users constantly. You cannot type *.example.com into the whitelist and have it work. The whitelist does not accept wildcards through the web interface. If you need to unblock an entire domain and all its subdomains, you have two practical options:

  1. Regex whitelist (covered in the next section). This is the correct tool for a wildcard-style allow rule.
  2. Remove the domain from your blocklists entirely. If you control the blocklists Pi-hole subscribes to, you can remove the offending list. But that unblocks everything on that list, not just the one domain you need.

When a wildcard blacklist is the cause: Check the query log. If a domain shows Blocked (wildcard), a wildcard blacklist entry is responsible. You can find it under Domains in the admin interface. The entry might look like (wildcard) cdn.example.com. Deleting that wildcard entry removes the block for the whole subtree. If you did not add it yourself, it may have come from a list you imported or a script you ran. Audit your domain entries to see what is there.

The regex workaround for wildcard whitelisting: Since the whitelist has no wildcard syntax, you use a regex whitelist to achieve the same effect. A regex whitelist entry of (^|\.)example\.com$ matches example.com and every subdomain under it. This sits at priority 3 in the decision chain, above regex blacklists and wildcard blacklists, so it overrides a wildcard block. I will break that regex down in the next section.

Regex: when patterns are the only way

Regex whitelisting is the most powerful override Pi-hole offers, and the easiest to get wrong. A regex entry matches any domain whose string representation satisfies the pattern. You can match partial names, multiple TLDs, or specific subdomain structures that exact and wildcard entries cannot express.

When to use it: - You need to unblock a domain and all its subdomains (the wildcard whitelist use case). - A service uses multiple top-level domains: service.co.uk, service.de, service.com.au. - A domain appears with variable prefixes: img1.service.com, img2.service.com, static-01.service.com. - You need to unblock a domain only for specific clients using Pi-hole’s group management, and regex is the only rule type that cleanly integrates with group assignment in the web interface.

How to add a regex whitelist: - Go to Whitelist in the admin interface. - Switch to the Regex tab. - Enter your pattern and click Add.

Essential regex patterns for Pi-hole:

Pattern Matches Does NOT match
(^\|\.)example\.com$ example.com, www.example.com, deep.sub.example.com notexample.com, example.com.evil.net
\.example\.com$ www.example.com, sub.example.com example.com
^example\.com$ example.com only www.example.com
^(.+\.)?example\.com$ example.com, any.sub.example.com notexample.com

The pattern (^|\.)example\.com$ is the one I recommend for a wildcard-style whitelist. Let me break it down character by character, because regex in DNS contexts has a specific job and small mistakes produce patterns that match nothing.

  • (^|\.) — The domain must either start (^) with example.com or be preceded by a literal dot (\.). This prevents matching notexample.com.
  • example — The literal domain name. The dot before com is escaped as \. because an unescaped dot in regex means “any character.”
  • \.com$ — The string must end with .com. The $ anchor prevents matching example.com.evil.net.

The number one regex mistake: Forgetting to escape the dots. If you write (^|.)example.com$, the unescaped dots match any character. exampleXcom would match. Pi-hole will not warn you; the regex simply behaves incorrectly. Always write domain dots as \. in regex patterns.

Testing your regex: Pi-hole includes a regex tester in the admin interface. Go to Whitelist > Regex and look for the test field. Paste the domain you want to match and see if your pattern highlights it. Test edge cases: the bare domain, a deep subdomain, and a domain that looks similar but should not match. If notexample.com lights up, your anchors are wrong.

Performance note: Pi-hole compiles regex entries and evaluates them in order for every DNS query that reaches that step in the chain. A handful of regex entries has negligible impact. If you accumulate dozens of complex patterns with nested quantifiers, you may see a measurable increase in query latency on underpowered hardware like a Raspberry Pi Zero. Keep regex entries specific and avoid overly broad patterns like .* unless you genuinely mean “match everything.”

Worked example: a CDN that breaks a banking site

Here is a realistic scenario that ties the three methods together. A user reports that their online banking portal shows a blank page after enabling Pi-hole. The main site loads, but the account dashboard never appears.

Step 1: Query log investigation. The query log shows www.bank.example as OK. But cdn.bank.example and assets.cdn.bank.example both show Blocked (wildcard). A wildcard blacklist entry for cdn.bank.example is catching every subdomain under the CDN.

Step 2: Decision. The bank uses a handful of CDN subdomains, all under cdn.bank.example. Unblocking the entire cdn.bank.example subtree is appropriate because the bank controls that namespace and it is unlikely to serve tracking or advertising content from it. A regex whitelist is the right tool.

Step 3: Add the regex whitelist. Navigate to Whitelist > Regex and add:

(^|\.)cdn\.bank\.example$

This matches cdn.bank.example and any subdomain under it, such as assets.cdn.bank.example. It sits at priority 3 in the decision chain, above the wildcard blacklist that was blocking it.

Step 4: Verify. Return to the query log. Within a minute, new queries for cdn.bank.example subdomains should show OK (whitelisted, regex). The banking portal loads correctly.

What if the problem was different? If only assets.cdn.bank.example was blocked and cdn.bank.example was fine, an exact whitelist for assets.cdn.bank.example would have been sufficient and safer. If the bank’s CDN used random subdomains like a1.cdn.bank.example, z9.cdn.bank.example, the regex approach is the only practical fix.

How to undo a rule that breaks things

Overly broad regex entries are the most common source of self-inflicted blocking gaps. If you add a regex whitelist for (^|\.)example\.com$ and later realize ads.example.com is now serving intrusive ads again, you need to tighten the rule.

Options for narrowing a regex whitelist: - Replace the broad pattern with exact whitelist entries for the specific subdomains you need. - Rewrite the regex to exclude the problematic subdomain. For example, (^|\.)(www|cdn)\.example\.com$ matches only www and cdn subdomains. - Use Pi-hole’s group management to apply the regex whitelist only to the client that needs it, leaving other devices fully protected.

To remove a rule, go to the appropriate list (Whitelist, Regex Whitelist, or Domains), find the entry, and click the trash icon. The change is immediate for new queries.

Auditing your rules periodically: Pi-hole’s Whitelist and Domains pages show every manual entry you have added. If you have been troubleshooting for months, you may have accumulated entries for services you no longer use. Delete anything you do not recognize or no longer need. A clean rule set is easier to reason about and less likely to contain conflicting entries.

Quick-reference decision table

Situation Tool Priority
One specific subdomain is blocked Exact whitelist 1 (highest)
A domain and all its subdomains are blocked by a wildcard entry Regex whitelist: (^\|\.)domain\.com$ 3
A domain appears with unpredictable numeric prefixes Regex whitelist 3
You accidentally wildcard-blocked a domain you need Delete the wildcard from Domains page N/A
A blocked domain is only needed by one device on your network Regex whitelist with group assignment 3

Conclusion

Pi-hole’s blocking is deterministic. When a site breaks, the query log tells you exactly which domain was blocked and by what mechanism. The fix is a matter of choosing the narrowest override that restores function without reopening the door to tracking.

Start with the query log every time. If the blocked domain is a single, predictable FQDN, use an exact whitelist. If a service sprawls across unpredictable subdomains, reach for a regex whitelist with the (^|\.) pattern and escaped dots. Test your regex before trusting it, and clean up old rules when they outlive their usefulness. The goal is not to disable Pi-hole for a site you trust—it is to unblock only the specific names that site needs to work, and nothing more.