$ ssh <username>@pi-hole.local
Internet advertising can often be a nuisance. It takes up valuable bandwidth. It weighs your browser down with trackers. It reports your data back to untrustworthy third parties.
On some devices, like laptops and phones, you can use ad blockers to protect yourself (and your sanity). But on many smart devices, like TVs, refrigerators, toasters, and toilets, you can’t install an ad blocker.
Pi-hole simplifies ad blocking by operating at the network level, instead of on individual devices. That way, you aren’t restricted by which devices can install an ad-blocker; instead, you can protect devices on your network from ever accessing ads in the first place.
Pi-hole blocks ads by acting as a DNS sinkhole.
To understand what a DNS sinkhole is, you need to understand what DNS is. Here are a few key terms:
unique alphanumeric address of a web resource (e.g.
unique numeric address of a web resource (e.g.
Domain Name System, associates domain names with IP addresses
a server that translates domain names into IP addresses
When you type
www.raspberrypi.com into your browser, your computer asks a DNS server where to find that domain. The DNS server responds with an IP address (e.g.
184.108.40.206). Then your computer queries that IP address for the resource you’re looking for.
We use domain names because IP addresses aren’t very human-readable; it’s a lot easier to read and write "raspberrypi.com" than four bytes' worth of numbers.
Usually, your computer queries a DNS server hosted somewhere on the internet. It might be hosted by your internet provider, a website hosting company, or any company that runs a lot of servers. Your machine submits a domain, and the DNS server returns the IP address corresponding to that domain. The DNS server doesn’t care if the domain provides something you want (like the article you’re trying to read) or an ad. It just resolves domains into IP addresses.
Here’s where Pi-hole comes in. Pi-hole stands between your network and a DNS server. Consider a client device, like your smart toilet, performing a DNS lookup for a domain. The Pi-hole in your network acts like a DNS server; DNS lookups from all client devices, whether that’s your smart toilet or your phone, go to the Pi-hole.
But Pi-hole doesn’t store a perfect up-to-date mapping of all domain names to all IP addresses. Instead, Pi-hole queries a real DNS server outside of your network. However, before it queries that real DNS server, Pi-hole checks a blocklist. If the domain passes this filter, Pi-hole requests the IP address from the DNS server, and returns it to the client device on your network. If the domain doesn’t pass the filter — if it’s included on the blocklist — Pi-hole returns a non-routable address such as
The following diagram shows a lookup via a Pi-hole for the unblocked domain
The following diagram shows a lookup via a Pi-hole for the blocked domain
TL;DR: Pi-hole blocks requests made to ad domains from your network, before the requests ever leave your network. Your client devices can’t connect to domains that host ads, but can connect to domains that host useful content.
To install a Pi-hole in your network, you’ll need to do the following things:
Configure a Raspberry Pi running Raspberry Pi OS.
Set up Pi-hole software on your Raspberry Pi.
Direct DNS queries on your network to your Raspberry Pi.
For the initial SD card setup, you will need:
Another computer connected to your network. We’ll refer to this as your usual computer to distinguish it from the Raspberry Pi computer you are setting up.
You can use any Raspberry Pi model for this. We recommend Zero 2 W if you can’t decide which model to use.
To begin, follow the Getting Started documentation to set up your Raspberry Pi. For your operating system, choose Raspberry Pi OS Lite (32-bit) to run headless (without a mouse and keyboard).
During the OS customisation stage, edit settings as follows:
Enter a hostname of your choice (we suggest
pi-hole for this tutorial)
Enter a username and password; you’ll need these later to authenticate
Check the box next to Configure wireless LAN so your Pi can automatically connect to Wi-Fi
Enter your network SSID (name) and password; you can find these in your Wi-Fi settings or on a sticker on your router
Check the box next to Enable SSH so we can connect to the Pi without a mouse and keyboard
Open a terminal on your computer. If you use a Windows computer, you may need to install a terminal; we suggest PuTTY. Enter the following command to connect to your Raspberry Pi, replacing the
<username> placeholder with your own username that you chose in Imager:
$ ssh <username>@pi-hole.local
ssh asks you if you’re sure you want to continue connecting, reply
yes. Enter the password you chose during advanced configuration when prompted.
You’ll know you’ve connected successfully when you see the following prompt with your configured username and hostname:
Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:
$ sudo apt update
$ sudo apt full-upgrade
Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:
$ sudo reboot
Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the
ssh connection command again to reconnect to your device.
Run the following single-line command to run the Pi-hole setup script:
$ curl -sSL https://install.pi-hole.net | bash
The setup script is relatively self-explanatory, but follow these tips if you aren’t sure how to proceed:
When warned about needing a static IP address, click Continue to proceed; we’ll deal with this later
When prompted to select an interface, select
wlan0 to use your Raspberry Pi’s Wi-Fi connection
When prompted to choose an upstream DNS provider, choose OpenDNS
Include StevenBlack’s Unified Hosts List
Install the Admin Web Interface
lighttpd and the required PHP modules to run the Admin Web Interface
Enable query logging
When prompted to choose a privacy level, choose Anonymous mode
When you see "Installation complete!", the setup is complete. This screen shows the IP address of your Pi-hole, a link to the admin interface, and your administrator password.
Save this password somewhere safe, like a password manager — you’ll need it to work with your Pi-hole in the future
Save the IP address — you’ll need it to configure a static IP address shortly
Pi-hole only provides a single administrator account, so there’s no username.
Press the Control key (Command on macOS) and click the link to the admin interface that uses an IP address. It’ll look something like
http://192.168.1.24/admin. Don’t use the
pi.hole domain link yet; until we configure the Pi-hole as our DNS provider, it won’t work. The link should open in your browser. You can also copy and paste the link into a browser if control + click doesn’t work in your terminal.
Use the admin password from the setup script output to authenticate. You can now see your Pi-hole admin console! We recommend bookmarking this console for future maintenance.
The tasks below require you to change global settings in your wireless network. You might break your internet connection (for a little while). Proceed with caution!
To complete these tasks, visit the admin interface for your router. You can usually access the admin interface through your router’s IP address. Here are a couple of common ways to find that interface:
Run the following command on your Raspberry Pi to output your router’s IP address:
$ nmcli -f IP4.GATEWAY device show wlan0
Check for a sticker on your router — look for a value called "admin URL" or similar
Once you’ve found the IP address, log in to your router’s admin interface by typing the address (sometimes with the suffix
/admin) into your browser. Enter your username and password (if you don’t know these, you may be able to find them on a sticker on your router).
Now that you’ve got your Pi-hole configured, you have three choices to use it to block ads. All of them involve getting Pi-hole between your network and the internet:
configure Pi-hole as the DNS server for your network
configure Pi-hole as the DHCP provider for your network
manually point devices at Pi-hole for DNS
It’s easiest to use your Pi-hole as a DNS server. However, some routers don’t provide a setting to control the default DNS server. If you can’t set a DNS server, try configuring Pi-hole as your DHCP provider. And if you can’t do that either, you can always manually point devices at the Pi-hole for DNS — it’s not as good as full-network ad blocking, but it’s a lot better than nothing.
This is the most common way of configuring a Pi-hole. For this method, you’ll first assign your Raspberry Pi a static IP address from your router’s interface, then point your router’s DNS server settings to the Pi-hole’s static IP address. With this setup, your router controls IP reservations across your network, but devices on the network send DNS queries to your Pi-hole instead of to a DNS server on the internet.
IP addresses are unique numeric codes that allow you to directly interact with devices on your network. For instance, many routers automatically assign themselves the first address in the IP block they are using, such as
192.168.1.1. Most networks use Dynamic Host Configuration Protocol (DHCP) to assign IP addresses to devices automatically. These IP addresses are known as dynamic IP addresses, because they can change at any time.
To run a Pi-hole on your network, we recommend assigning your Pi-hole a static IP address. A static IP address never changes. This allows devices on your network always to find the Pi-hole at the same address.
To start, run the following command on your Raspberry Pi:
$ hostname -I
You should see output similar to the following:
This value is the current (dynamic) IP address of your Raspberry Pi on the network.
To assign a static IP address, you also need the MAC address of your Raspberry Pi. A device’s MAC address is a hardware identifier that your router uses to uniquely identify it. Run the following command to find the MAC address of your Raspberry Pi:
$ nmcli -f GENERAL.HWADDR device show wlan0
You should see output similar to the following:
The value on the right is the MAC address of your Raspberry Pi. Now that we know your Raspberry Pi’s MAC address and IP address, we can configure your router so it always associates the Raspberry Pi’s MAC address with its current IP address. Effectively, we’re turning the current dynamic address into a static one using the MAC address. In your router’s admin interface, configure a static IP address for your Raspberry Pi. There are several ways to accomplish this, depending on your router:
You might be able to find this setting in the "Advanced" section of the router admin interface. Look for a list called "DHCP Reservations", and enter your Raspberry Pi’s IP address and MAC address.
Look for a list of connected devices and find your Raspberry Pi’s IP address or MAC address. Select the option to "Always use this IP address" to make the IP address reservation static.
Check the documentation for your router model for specific instructions.
Once you’ve assigned your Raspberry Pi a static IP address, you can configure individual devices to use Pi-hole as a DNS server in their network settings. But this process is tedious, and some devices don’t provide an easily accessible DNS server setting. However, there is an easier way: most routers automatically suggest a DNS server for devices connected to your network. All you have to do is change the suggested server in your router’s settings, and your entire network should start using your Pi-hole for DNS.
Look for a setting called DNS in your router’s admin interface. You may be able to find the setting in a section called "Internet", "DHCP", "Internet Connection", or "DDNS".
Enter your Pi-hole’s IP address in the DNS (or similarly named) field.
If your router provides multiple custom DNS fields, add your Pi-hole address in each field.
Whatever you do, don’t add any separate DNS entries after the Pi-hole entries — this can break Pi-hole’s ad blocking functionality. When your Pi-hole blocks a domain, it returns a non-routable address such as
0.0.0.0, and some devices will query the secondary DNS server when the first server returns such a non-routable address. If your secondary DNS server isn’t a Pi-hole, every single request blocked by Pi-hole will succeed on the secondary server, and ads will load as if you weren’t running an ad blocker at all.
If your router doesn’t support configuration for static IP addresses or DNS servers, you may still be able to use your Pi-hole automatically across your network. First, check whether you can change the network DHCP server in your router settings. If you can, you can use your Pi-hole both as a DNS server and as the DHCP server that handles IP address reservations across your network.
First, navigate to the Pi-hole admin console. If you type your Raspberry Pi’s IP address into your browser, it should redirect you there.
In the left side menu, select the "Settings" page.
In the DHCP tab, in the "DHCP Settings" block, check the "DHCP server enabled" box.
Pi-hole should pre-populate the IP address range with the IP block that your router currently uses, and the router IP address with the router’s current IP address. You can leave these values as they are. Click the Save button in the bottom left to start hosting a DHCP server from Pi-hole.
Finally, visit your router’s admin interface, and set your Pi-hole’s IP address as the DHCP provider for your network. When your Pi-hole is functioning as the DHCP provider, your router delegates all IP-related tasks to it. This includes DNS server configuration, so your Pi-hole can suggest itself as the default DNS server for all devices on your network. Check the documentation for your router model for specific instructions.
On many devices, you can configure DNS settings in Wi-Fi preferences. Look in the "Advanced" section of your Wi-Fi or wired connection preferences for a DNS server setting. Put your Raspberry Pi’s IP address in this field. Your device should immediately start issuing DNS queries to the Pi-hole.
Unless you’ve configured a static IP address for your Raspberry Pi, this IP address can change at any time without warning. Follow the instructions under "Assign your Raspberry Pi a static IP address" in the DNS section above to configure a static IP address — this will prevent your device from losing its connection to the Pi-hole (and most of the internet!) when your Pi-hole’s dynamic IP address changes.
With a Pi-hole acting as the DNS server for your network, many pages will load without ads at all. Most privacy-invading trackers won’t work either. You’ll still see cookie and app install banners, because those can’t be blocked at the DNS level. To check to see if your Pi-hole is working correctly:
Check out Adblock Tester. Without Pi-hole, many browsers score near 0; with Pi-hole, you should see a score at or near 100.
Try visiting http://pi.hole/admin/login.php. Pi-hole always routes the
pi.hole domain to your Raspberry Pi when you use Pi-hole as your DNS server.
Visit any site where you normally see ads and visually confirm that ads are no longer there.
Check the proportion of "queries blocked" on the Pi-hole dashboard. Many networks see between 10% and 50% of queries blocked!
Check the DNS server used by other computers in your network. You should be able to find this information in "Details" or "Advanced" Wi-Fi settings. If you see your Raspberry Pi’s IP address, your configuration worked!
If you’ve completed all of the setup steps but you’re still seeing ads (or, worse, DNS queries don’t resolve), try the trusty solution of turning your router off and on again. This should disconnect all devices from your network and renew all DHCP leases, putting your new settings into effect for every device. Congratulations! Your home network is now protected from ads. Put a slice of bread in your smart toaster, watch a movie on your smart TV, and flush your smart toilet in the comfort of privacy and security.