How to Install Pi-hole on Raspberry Pi to Block Ads
Step-by-step guide to installing Pi-hole v6 on a Raspberry Pi to block ads and trackers across your whole home network, from static IP to router setup.
If you spend any time on the internet, you're probably all too familiar with ads everywhere: banners covering the article you're reading, video ads that suddenly start playing with sound, and ads inside phone apps and on your Smart TV. On top of that, plenty of trackers quietly record which sites you visit.
A browser ad blocker extension helps, but it only works inside that browser. What about the apps on your phone, your Smart TV, your game console, or the IoT gadgets around your home? Installing an ad blocker on every device one by one is a hassle, and many devices simply can't run one at all.
This is where Pi-hole comes in. All you need is one small Raspberry Pi running 24/7, and every device on your home network is instantly protected from ads and trackers, without installing anything on those devices.
In this article, we'll cover everything about installing Pi-hole on a Raspberry Pi, from how it works, setting up a static IP, installing Pi-hole v6, and configuring your router so every device uses Pi-hole, to maintenance tips and adding Unbound for extra privacy. Let's get started!
Pi-hole is an open source application that acts as a DNS sinkhole: a DNS server that "swallows" requests to ad and tracker domains so they never reach their destination. Despite the "Pi" in its name, Pi-hole can run on many Linux systems, but the Raspberry Pi is its favorite home because it's power efficient and can stay on all the time.
To understand how it works, we first need to know what DNS (Domain Name System) is. Every time you open a website, your device asks a DNS server: "What's the IP address of teknotut.com?" The DNS server replies with the IP address, and only then does your device connect to the site.
Think of Pi-hole as a receptionist at your front door. Every time a device wants to "call" a domain, the receptionist checks a blocklist first:
If the domain is normal (for example teknotut.com), the request is forwarded to an upstream DNS server and the answer is returned as usual.
If the domain is on the blocklist (for example an ad domain), Pi-hole answers with the empty address 0.0.0.0. As a result, the ad never loads.
Because it works at the DNS level, Pi-hole blocks ads before they are downloaded. Web pages feel lighter, and you save bandwidth too.
Since February 2025, Pi-hole has been at version 6, which brought major changes: the web server is now embedded directly in pihole-FTL (no more lighttpd and PHP), there's a new REST API, built-in HTTPS support, and all configuration now lives in a single file, /etc/pihole/pihole.toml. At the time of writing, the latest release is FTL v6.8, Web v6.6.1, and Core v6.5.
These changes are worth knowing about, because many older tutorials online still cover Pi-hole v5, for example the pihole -a -p command to change the password or the setupVars.conf file, which no longer apply in v6.
To keep things balanced, here are a few limitations you should know about:
It can't block every ad: ads served from the same domain as the content, such as YouTube video ads or Instagram ads, can't be blocked at the DNS level. You'll still need a browser ad blocker for those.
It becomes a single point of failure: if the Raspberry Pi goes down and every device depends on it, your home internet will feel "broken" because nothing answers DNS requests. We'll cover how to deal with this in the router section.
It sometimes blocks things it shouldn't: overly aggressive blocklists can break certain sites or apps. You can add such domains to the allowlist.
A Raspberry Pi of any model still supported by the latest Raspberry Pi OS, such as a Pi 3, Pi 4, Pi 5, or Zero 2 W. Pi-hole only needs 512 MB of RAM and 2 GB of free space (4 GB recommended), so even an older Raspberry Pi is more than enough.
Raspberry Pi OS Lite, installed and reachable over SSH. The commands in this article are intended for Raspberry Pi OS Bookworm (Debian 12) and Trixie (Debian 13). If you haven't installed it yet, follow the guide on how to install Raspberry Pi headless.
An Ethernet cable (highly recommended). A DNS server should be wired for better stability than WiFi.
Access to your router's admin page, because we'll need to change the router's DNS settings later.
Important: Pi-hole needs port 53 (DNS) and ports 80 and 443 (web interface) to be free. If your Raspberry Pi already runs another application on those ports, such as a web server or another DNS server, Pi-hole will try ports 8080 and 8443 for its web interface. For the easiest results, use a clean Raspberry Pi.
In the examples in this article, we'll use the router IP address 192.168.1.1 and the Raspberry Pi IP address 192.168.1.10. Adjust them to match your own network.
Pi-hole is a server, so its IP address must not change. Imagine if our receptionist moved to a different address every day; nobody would be able to find them, right? If the Raspberry Pi's IP changes, every device at home loses its DNS server.
There are two ways to give the Raspberry Pi a fixed IP. The recommended way is a DHCP reservation on your router, which tells the router to always hand out the same IP to the Raspberry Pi. This menu is usually called DHCP Reservation, Address Reservation, or Static Lease, depending on your router brand. Just pick the Raspberry Pi from the client list and assign it 192.168.1.10.
If your router doesn't have that feature, set the static IP directly on the Raspberry Pi. Raspberry Pi OS Bookworm and Trixie use NetworkManager, so we configure it with nmcli. First, list the active connection names:
nmcli connection show
The output will look roughly like this:
NAME UUID TYPE DEVICEWired connection 1 2c4b7f2e-7a11-3d5e-9c55-1f0a0b6b9e21 ethernet eth0lo 6d1e5b0a-2f6c-4c0a-a3a4-8e2b1f9d7c10 loopback lo
Note the connection name in the NAME column for the eth0 device (Wired connection 1 in the example above; yours may be different). Then set the static IP with the following command, adjusting the connection name, IP, and gateway to match your network:
Apply the change by bringing the connection up again:
sudo nmcli connection up "Wired connection 1"
Note: if you're connected over SSH and the IP changes, your SSH session will drop. That's normal. Log back in using the new IP, for example ssh [email protected]. Also make sure the IP you choose is outside the router's DHCP range so it doesn't clash with another device.
To confirm the IP is correct, run the following command:
hostname -I
If the output shows 192.168.1.10, the static IP is active.
Pi-hole provides a very easy automated installer. The official way is to run this one-liner:
curl -sSL https://install.pi-hole.net | bash
Security tip: piping a script from the internet straight into bash is convenient, but some people prefer to read it first. If you're the careful type, download the script, review it, and then run it:
The installer checks your system, installs the required packages, and then shows a series of dialogs. Use the arrow keys to move between options, Space to select, and Enter to continue.
Here's the order of the dialogs you'll see, along with our suggested choices:
Pi-hole Automated Installer: the welcome screen. Press Enter to continue.
Static IP Needed: a warning that Pi-hole needs a static IP. Since we set one up in step #2, choose Continue.
Choose An Interface: choose eth0 if the Raspberry Pi uses Ethernet, or wlan0 if it uses WiFi. If only one interface is active, this dialog is skipped automatically.
Select Upstream DNS Provider: choose the DNS server Pi-hole will use to resolve domains that aren't blocked. Popular choices are Cloudflare (DNSSEC) or Quad9 (filtered, DNSSEC). You can change this at any time later.
Blocklists: choose Yes to use the default blocklist, StevenBlack's Unified Hosts List. It's a solid list to start with.
Enable Logging: choose Yes if you want to see DNS request history on the dashboard. This is very helpful when figuring out which domain is breaking a site.
Select a privacy mode for FTL: sets how much detail is shown on the dashboard. For a private home network, choose 0 Show everything. If the Pi-hole is shared with family or other people, you can pick a more private level.
The installation will continue and usually finishes within a few minutes, depending on your internet speed and Raspberry Pi model.
At the end of the installation, Pi-hole shows a summary with the web interface address and a randomly generated admin password, roughly like this:
View the web interface at http://pi.hole/admin or http://192.168.1.10/adminYour Admin Webpage login password is Xa7kP2qd
Write that password down, because you can't view it again. Pi-hole only stores its hash in pihole.toml. If you forget it, or want to replace it with your own easier-to-remember password, use the following command:
sudo pihole setpassword
You'll be asked to type the new password twice (it isn't shown on screen as you type).
So your user can run pihole commands without always typing sudo, add it to the pihole group:
sudo usermod -aG pihole $USER
Log out and log back in so the new group membership takes effect.
Open a browser on a computer connected to the same network and go to the following address:
http://192.168.1.10/admin
Enter the admin password from the previous step, and you'll be greeted by the Pi-hole dashboard, showing the number of DNS queries, blocked domains, the block percentage, and the number of domains on your blocklist.
Note: the dashboard will be quiet at first because no devices are using Pi-hole as their DNS yet. Pi-hole also serves HTTPS at https://192.168.1.10/admin with a self-signed certificate, so your browser will show a warning. That's expected on a local network.
Before changing your router settings, let's make sure Pi-hole is already blocking ad domains. From another computer on the same network, run the following command (on Windows, nslookup is also available in Command Prompt or PowerShell):
If the returned address is 0.0.0.0, Pi-hole is working and has blocked that domain. Try a normal domain like teknotut.com as well; the result should be a valid IP address.
Pi-hole is running, but the devices in your home aren't using it yet. There are three ways to point devices at Pi-hole, listed from most to least recommended.
This is the best option, because every device that connects over WiFi or LAN automatically uses Pi-hole. Log in to your router's admin page (usually http://192.168.1.1), then look for the LAN or DHCP Server menu. There you'll usually find Primary DNS and Secondary DNS fields.
Set Primary DNS to the Raspberry Pi's IP, 192.168.1.10.
Be careful with Secondary DNS. If you fill it with a public DNS server such as 8.8.8.8, devices may use it at any time and ads will slip through. On the other hand, if you only use Pi-hole, the internet will "break" whenever the Raspberry Pi is down. For consistent blocking, leave Secondary DNS empty or set it to the same Pi-hole IP. If you need a fallback, the best solution is a second Pi-hole on another device.
After saving, devices will pick up the new DNS when their connection renews. The quickest way is to disconnect and reconnect WiFi on your device.
Don't change the DNS on the WAN page. Some routers also have DNS settings on the WAN or Internet page. That's the DNS the router itself uses, not the DNS handed out to devices. Changing it makes every query on the Pi-hole dashboard appear to come from the router, so you lose per-device statistics.
Some ISP-provided routers don't let you change the DNS. If that's your situation, Pi-hole can take over the DHCP server role from the router.
The order matters: turn off the router's DHCP server first, then enable DHCP in Pi-hole via Settings → DHCP in the web interface. Never have two DHCP servers active on the same network, or devices may end up with messed-up IP addresses.
If neither option above works, you can change the DNS manually in each device's network settings. It's tedious, but useful if you only want to protect a few specific devices or just want to try Pi-hole first.
Note for Android: Android's Private DNS feature (DNS-over-TLS), when set to a specific provider, bypasses Pi-hole. If ads still appear on your Android phone, check this setting and change it to Off or Automatic. The same applies to the DNS-over-HTTPS feature in some browsers.
Besides the web interface, Pi-hole can be fully managed from the terminal. Here are the most commonly used commands:
Command
Purpose
pihole status
Check whether DNS and blocking are active
pihole -up
Update Pi-hole to the latest version
pihole -g
Update the blocklists (gravity)
pihole disable 5m
Temporarily disable blocking for 5 minutes
pihole enable
Re-enable blocking
pihole tail
Watch DNS queries in real time
pihole -q domain.com
Check whether a domain is on a blocklist
sudo pihole setpassword
Change the web interface password
pihole -v
Show the Pi-hole version
pihole repair
Repair the installation without losing your settings
The pihole tail command is very handy when a site won't open. Run it, open the problematic site, and watch which domains are logged as blocked. Those are the domains you may need to add to the allowlist.
The default StevenBlack list is enough for most people. If you want to add more, open Group Management → Lists in the web interface, paste the blocklist URL, and click Add blocklist. Then update gravity with pihole -g or via Tools → Update Gravity.
Remember, more lists doesn't mean better. The more aggressive your blocklists, the more likely something breaks.
If a site misbehaves after you start using Pi-hole, for example promotional links in emails that won't open, find the domain in the Query Log and click Allow next to it. You can also add it manually from the Domains menu.
The Pi-hole team releases updates fairly regularly, including security fixes. For example, the FTL v6.8 release in October 2026 patched several high-severity vulnerabilities. Make a habit of updating Pi-hole and the operating system every few weeks:
Pi-hole is designed for local networks. Never expose your Raspberry Pi's port 53 to the internet through port forwarding on your router. A publicly open DNS server can be abused for DDoS attacks (DNS amplification). If you want to use Pi-hole while away from home, use a VPN such as WireGuard.
By default, Pi-hole forwards unblocked DNS requests to an upstream provider such as Cloudflare or Quad9. That means the provider can still see which domains you visit.
Unbound is a recursive DNS resolver that can run on the same Raspberry Pi. With Unbound, Pi-hole no longer depends on a third party, because Unbound asks the root servers and each domain's authoritative servers directly.
Install Unbound with the following command:
sudo apt install unbound -y
Create a dedicated configuration file for Pi-hole:
Save with CTRL+X, then Y, and Enter. Unbound will listen on 127.0.0.1 port 5335, so it's only reachable from the Raspberry Pi itself and doesn't clash with Pi-hole on port 53.
On Debian Bullseye and newer (including Raspberry Pi OS Bookworm and Trixie), the Unbound package ships an unbound-resolvconf.service that can mess up the system's DNS settings. This service writes nameserver 127.0.0.1 without a port into /etc/resolv.conf. The Pi-hole documentation recommends disabling it and removing its extra configuration with the following commands:
If dig isn't available yet, install it first with sudo apt install dnsutils -y. In the output, look for the status: NOERROR line and an IP address in the ANSWER SECTION. The first query is usually a bit slow, but later queries for the same domain will be much faster because they're cached.
Finally, point Pi-hole at Unbound. Open the web interface, go to Settings → DNS, uncheck all the built-in upstream DNS servers, and enter the following in the Custom DNS servers field:
127.0.0.1#5335
Click Save & Apply. Done! Your Pi-hole now blocks ads and resolves DNS on its own without relying on any DNS provider.
From this article, we can conclude that Pi-hole is the most practical way to block ads and trackers across your entire home network at once. With just one Raspberry Pi, a static IP, the official installer, and a small DNS change on your router, every device from your phone to your Smart TV is protected right away.
With Pi-hole running, your Raspberry Pi is now officially a small home server. You can go further by adding Unbound as shown in the bonus section, or use the same Raspberry Pi for other projects like reading a DHT22 temperature sensor. If you prefer running applications in containers, Pi-hole is also available as an official Docker image that you can run with Docker Compose.
If you have any questions or run into problems during installation, feel free to ask. Stay tuned to Teknotut!