The Blackhole: A network-wide ad blocker in a case the size of a biscuit — Build Guide

A Raspberry Pi Zero 2 W running Pi-hole blocks ads for every device on your network before they reach your phone, laptop or tablet. You install it once, point your router at it, and advertisements disappear from browsers, apps and smart TVs without touching a single device. The whole thing fits in a case smaller than a pack of cards and draws about two watts.

Key points

• Pi-hole runs on a Raspberry Pi Zero 2 W and intercepts DNS requests for ad domains, returning nothing instead of an advertisement.
• Every device on your network benefits at once — no per-device configuration, no browser extensions, no app settings to change.
• The admin dashboard shows which domains were blocked and which devices requested them, in real time.
• Total power draw sits around two watts, less than a phone charger left plugged in.
• The base build takes one evening if you have flashed an SD card before, two if this is your first.
• You can break your household's internet access if you misconfigure it, and you will need your router's admin password to undo that.

What you are building and why it is worth one evening

Pi-hole is a DNS server that returns an empty response when a device asks for an ad domain. Your phone requests tracker.example.com, Pi-hole says that domain does not resolve, and the ad never loads. Install it on a Raspberry Pi Zero 2 W and every device on your network goes through it without knowing.

This is the classic first Raspberry Pi project. You flash an SD card, copy commands from a guide, point your router at the Pi's IP address, and ads stop appearing. The dashboard tells you which domains were blocked, which device made the request, and how many queries Pi-hole handled today.

It works on devices you cannot install an ad blocker on: smart TVs, IoT cameras, mobile apps. Some of those will break when their telemetry is blocked, and you will have to whitelist the domain. That is the trade-off.

The parts list

Two items cover the build. The kit includes the board, the case, a power supply and the GPIO header already soldered. The microSD card needs to be fast enough that DNS lookups do not lag.

The kit's GPIO header is already soldered, which saves you the fiddly bit. The case has cutouts for all the ports. The power supply outputs 2.5 amps at 5 volts, enough for the Zero 2 W under load.

The microSD card's A2 rating matters more than its sequential speed. DNS lookups are random reads, and a slow card adds latency to every query. The 128 GB size is overkill for Pi-hole itself but means you will not run out of space as the query log grows.

What you supply yourself

You need your router's admin password. It is usually printed on a sticker on the router itself, and if it has been changed, it is wherever you wrote it down. You are going to change the DNS server setting in the router's web interface, and you cannot do that without the password.

You also need a microSD card reader if your laptop does not have one built in, and a computer running Windows, macOS or Linux. The Pi Zero 2 W can run headless from first boot, so you do not need a monitor or keyboard for the Pi itself.

A wired Ethernet connection for the Pi is better than Wi-Fi but not required. The kit's Zero 2 W has built-in Wi-Fi, and that is good enough for DNS queries. If you have a USB-to-Ethernet adapter and a way to power the Pi through its GPIO header, you can run it wired, but start with Wi-Fi and switch only if you see latency.

The build, in numbered phases

Phase one: flash the SD card and boot the Pi

Download the Raspberry Pi Imager from the Raspberry Pi Foundation's site. It runs on Windows, macOS and Linux and writes the OS to the SD card without extracting files manually.

Insert the SANDISK microSD card into your computer. Launch the Imager, select Raspberry Pi Zero 2 W as the device, choose Raspberry Pi OS Lite as the operating system, and select your SD card as the storage. Click the settings gear before you write.

In the settings, enable SSH, set a username and password you will remember, and configure your Wi-Fi network's SSID and password. Save the settings, click Write, and wait for the Imager to finish. This takes three to five minutes.

Eject the SD card, insert it into the Pi Zero 2 W, and connect the power supply. The Pi will boot, connect to your Wi-Fi, and become reachable over SSH. Give it two minutes.

Phase two: find the Pi's IP address and log in

Your router's admin interface shows connected devices. Log into the router, find the device list, and look for a hostname that matches what you set in the Imager. Write down its IP address.

Open a terminal on your computer. On Windows, use PowerShell or Windows Terminal. On macOS or Linux, use Terminal. Type ssh username@ip-address, replacing username and ip-address with what you set earlier. Press Enter, type yes when asked about the fingerprint, then enter your password.

You are now logged into the Pi. Run sudo apt update && sudo apt upgrade -y to update the system. This takes five to ten minutes on a fresh install.

Phase three: install Pi-hole

The Pi-hole installer is a shell script you run from their site. Type curl -sSL https://install.pi-hole.net | bash and press Enter. The installer asks a series of questions.

Select OK on the welcome screen. Choose your network interface — it will be wlan0 if you are on Wi-Fi. Select a public DNS provider as the upstream resolver; Cloudflare and Google are both fine. Accept the default blocklists. Install the web admin interface and the required web server. Enable query logging if you want to see which domains were blocked. Set a privacy level; level zero logs everything.

The installer finishes by showing you the admin password. Write it down. The web interface is at http://pi-ip-address/admin.

Phase four: configure your router to use Pi-hole

Log into your router's admin interface again. Find the DNS settings. This is usually under LAN, DHCP or Internet settings, and the exact location depends on your router's firmware.

Replace the primary DNS server address with the Pi's IP address. Leave the secondary DNS blank or set it to a public resolver as a fallback. Save the settings and reboot the router if it asks.

Devices on your network will pick up the new DNS server when they renew their DHCP lease. You can force this by disconnecting and reconnecting to Wi-Fi, or by rebooting the device. Open a browser on your phone, visit a site known for ads, and check if they load. If they do not, Pi-hole is working.

Where this build stalls and how to get unstuck

The SSH connection fails because you cannot find the Pi's IP address. Your router's admin interface is the only reliable way to see connected devices. If the Pi does not appear, check the Wi-Fi credentials you entered in the Imager and reflash the card.

The Pi-hole installer hangs during package installation. The Zero 2 W is slow, and some steps take five minutes. Let it run. If it genuinely stalls, press Ctrl+C, run sudo apt update again, and rerun the installer.

Ads still load after you point the router at Pi-hole. Some devices cache DNS responses or use hard-coded DNS servers that bypass your router's setting. Reboot the device to flush the cache. If ads still appear, check the Pi-hole dashboard to see if queries are arriving. If the dashboard shows no queries, the router is not forwarding DNS requests to the Pi.

Your internet stops working entirely. You misconfigured the router's DNS setting or the Pi is offline. Log into the router, change the DNS server back to the ISP's default or a public resolver like 1.1.1.1, save, and your internet will work again. Then troubleshoot why the Pi is not reachable.

Safety, etiquette and the cleanup that keeps you allowed to do this again

You have taken over DNS for the entire household. Everyone's internet now depends on the Pi staying up. If you unplug it to move it or the SD card corrupts, no one can resolve domain names and nothing will load.

Warn the people you live with that you are doing this, and tell them what to do if the internet breaks while you are out. The fix is to log into the router and change the DNS server back to what it was before. Write down the original DNS server address before you change it.

Pi-hole blocks some domains that are not advertisements. Streaming services sometimes break because Pi-hole blocks telemetry domains the app checks before playing video. When someone reports a site or app not working, open the Pi-hole dashboard, check the query log, and whitelist the blocked domain if it is legitimate. The dashboard has a one-click whitelist button next to every query.

The SD card will wear out eventually. They are not designed for constant writes, and Pi-hole logs every DNS query. Back up the Pi-hole configuration by exporting it from the web interface every few months. When the card fails, reflash a new one, install Pi-hole, and restore the configuration.

Ways to take it further once the base build works

Add more blocklists from the Pi-hole community. The default lists block major ad networks, but specialty lists exist for tracking domains, malware, and telemetry from specific vendors. Add them in the web interface under Group Management, then update the blocklist.

Set a static IP address for the Pi in your router's DHCP settings. This stops the IP from changing if the Pi reboots or the DHCP lease expires. You want the DNS server address to stay the same.

Configure conditional forwarding so Pi-hole shows device hostnames instead of IP addresses in the query log. This requires your router's local domain and IP range, which you enter in the Pi-hole DNS settings.

Enable DNSSEC in the Pi-hole settings to validate DNS responses. This adds a small amount of latency but stops DNS spoofing.

Run Pi-hole as a recursive DNS server using Unbound. This makes the Pi resolve domains itself instead of forwarding queries to Cloudflare or Google, which gives you more privacy but makes DNS queries slower.

Common questions

Does Pi-hole block YouTube ads?

No. YouTube serves ads from the same domains as the videos, so blocking the ad domain breaks video playback. Pi-hole cannot distinguish between an ad and a video when they come from the same server. You still need a browser extension for YouTube.

Will this slow down my internet?

DNS lookups add a few milliseconds, but you will not notice it. The Pi Zero 2 W handles hundreds of queries per second, and DNS is cached both on the Pi and on your devices. Your connection speed does not change — only the time to resolve a domain name, and that was already happening before Pi-hole.

Can I use this on a network I do not control?

No. You need admin access to the router to change the DNS server, and you need permission from whoever owns the network. Installing a Pi-hole on a work or university network without authorisation will get you fired or expelled. Use a browser extension instead.

What happens if the Pi loses power?

DNS stops working until the Pi boots again. Devices will time out trying to resolve domains, and nothing will load. This is why you write down the original DNS server setting — someone can change it back while you fix the Pi. The Zero 2 W boots in about thirty seconds once power is restored.

How much of my internet traffic does Pi-hole see?

Pi-hole sees DNS queries only. It knows which domains your devices requested and when, but it does not see the content of web pages, the data in HTTPS connections, or anything you type. It is not a proxy. If a domain resolves via DNS-over-HTTPS in the browser, Pi-hole does not see that query at all.

Can I block specific sites for specific devices?

Yes, but it requires setting up groups in Pi-hole. You assign devices to a group based on their IP address or MAC address, then assign blocklists to that group. A child's tablet can have stricter blocking than your laptop. This is fiddly and requires reading the Pi-hole documentation.

Does this work if my ISP forces their own DNS server?

Most ISPs do not force DNS at the router level. If yours does, you can work around it by setting the DNS server on each device instead of at the router, but that defeats the point of a network-wide blocker. Check your router's settings first — most let you override the ISP's DNS.

How often do I need to update Pi-hole?

Run pihole -up from the SSH session every few months to update Pi-hole itself. The blocklists update automatically once a week. The Raspberry Pi OS underneath needs sudo apt update && sudo apt upgrade every month or so. None of this is urgent, but old software eventually stops working.

Who this build is for and who should skip it

Build this if you want ads gone from every device without installing anything on those devices, and if you are comfortable troubleshooting DNS when something breaks. The dashboard alone is worth it — seeing how often your smart TV phones home is clarifying.

Skip it if you are the only person in the house who understands what DNS is. You will spend more time whitelisting domains for other people than you will save blocking ads. Also skip it if you rent and cannot guarantee the Pi will stay powered and connected. A browser extension does most of this without the fragility.