Single Board Computer (SBC)

Best Single Board Computers

How to Install Pi-hole on Raspberry Pi: Complete Guide

How to Install Pi-hole on Raspberry Pi: Complete Guide

Want to block ads, trackers, and unwanted domains across your entire home network without installing an ad blocker on every device?

Pi-hole turns a Raspberry Pi into a network-wide DNS filtering server. Once your router distributes the Raspberry Pi’s address as the DNS server, computers, phones, smart TVs, and other devices can send their DNS requests through Pi-hole and benefit from centralized blocking.

In this guide, you’ll learn how to install Pi-hole on Raspberry Pi OS, configure it with a static IP, connect it to your home network, and verify that DNS filtering is working.

What Is Pi-hole?

Pi-hole is a DNS sinkhole designed to block unwanted domains at the network level.

Instead of installing an ad-blocking extension on every browser, Pi-hole works between your devices and DNS servers:

                Internet
                    │
             Upstream DNS
                    │
                 Pi-hole
                    │
              Home Router
          ┌─────────┼─────────┐
          │         │         │
        Laptop    Phone     Smart TV

When a device requests a domain that appears on a Pi-hole blocking list, Pi-hole can prevent the request from reaching the destination.

This can help reduce:

  • Advertising domains
  • Tracking domains
  • Analytics requests
  • Known malicious domains
  • Unwanted network traffic

Pi-hole also provides a web dashboard where you can monitor DNS queries and manage allowlists, denylists, and groups.

Why Run Pi-hole on a Raspberry Pi?

A Raspberry Pi is particularly well suited to Pi-hole because Pi-hole is lightweight.

The official prerequisites list only 512 MB of RAM and at least 2 GB of free storage, making even relatively modest Raspberry Pi hardware capable of running it. Raspberry Pi OS is officially supported.

A Raspberry Pi 4 or Raspberry Pi 5 gives you plenty of resources if you also want to run other services.

Advantages

  • Very low power consumption
  • Small footprint
  • Affordable
  • Runs 24/7
  • Ethernet connectivity
  • Easy to administer remotely
  • Can run additional services

Hardware Requirements

You don’t need an especially powerful Raspberry Pi.

ComponentRecommendation
Raspberry PiRaspberry Pi 4 or 5
RAM1 GB+ recommended
Storage8 GB+
Operating SystemRaspberry Pi OS
NetworkEthernet recommended
PowerReliable Raspberry Pi power supply
IP addressStatic or DHCP reservation

Pi-hole officially requires only 512 MB RAM and 2 GB free storage, and Raspberry Pi OS is among its supported operating systems.

Do You Need an SSD?

No.

Pi-hole can run perfectly well from a microSD card because its hardware requirements are modest.

However, if your Raspberry Pi is already being used as a home server, an SSD is preferable.

Step 1: Install Raspberry Pi OS

Start with a clean installation of Raspberry Pi OS.

Using Raspberry Pi Imager, select:

  1. Raspberry Pi device
  2. Raspberry Pi OS
  3. Storage device

Before writing the image, configure:

  • Username
  • Password
  • Hostname
  • SSH
  • Network settings

For a dedicated Pi-hole server, Raspberry Pi OS Lite is a good option because it doesn’t require a graphical desktop.

Step 2: Connect to the Raspberry Pi

After booting the Raspberry Pi, determine its IP address.

You can check it from your router or run:

hostname -I

For example:

192.168.1.50

Connect over SSH:

ssh [email protected]

Replace the username and IP address with your own values.

Step 3: Update Raspberry Pi OS

Before installing Pi-hole, update the operating system:

sudo apt update
sudo apt full-upgrade -y

Then reboot:

sudo reboot

Reconnect using SSH after the Raspberry Pi restarts.

Step 4: Give Pi-hole a Stable IP Address

This is one of the most important steps.

Pi-hole needs a stable IP address because your network devices will use that address as their DNS server. The official Pi-hole documentation specifically recommends a static IP, and a DHCP reservation on your router is also acceptable.

For example:

Raspberry Pi
192.168.1.50

Your router should always assign:

192.168.1.50

to the Raspberry Pi.

DHCP Reservation vs Static IP

I generally recommend a DHCP reservation for beginners.

Configure the reservation in your router using the Raspberry Pi’s MAC address.

This avoids having to manually configure network settings on the Raspberry Pi.

Step 5: Install Pi-hole

Pi-hole’s official documentation provides a one-step automated installer.

Run:

curl -sSL https://install.pi-hole.net | bash

The installer launches an interactive setup process.

Security note: Pi-hole also provides alternatives if you don’t want to pipe a downloaded script directly into Bash. You can download the installer first, inspect it, and then execute it.

For example:

wget -O basic-install.sh https://install.pi-hole.net

Then:

sudo bash basic-install.sh

Step 6: Configure Pi-hole

The installer will guide you through several settings.

You’ll select things such as:

Network interface

Choose the interface connected to your network.

Usually this will be:

eth0

if you’re using Ethernet.

For Wi-Fi, it may be:

wlan0

Upstream DNS provider

Pi-hole needs an upstream DNS server for domains that aren’t blocked.

Depending on your preferences, you can select a provider such as:

  • Cloudflare
  • Google
  • Quad9
  • Other available providers

You can change this later from the Pi-hole settings.

Step 7: Complete the Installation

After the installer finishes, Pi-hole will provide information about accessing the web interface.

The web interface is normally available under:

http://PI-HOLE-IP/admin/

For example:

http://192.168.1.50/admin/

Open that address from another computer on your network.

Step 8: Set the Pi-hole Web Password

Pi-hole provides the pihole setpassword command for setting the web interface/API password.

Run:

pihole setpassword

Enter a strong password when prompted.

Avoid using the same password you use for your other services.

Step 9: Configure Your Router to Use Pi-hole

Installing Pi-hole isn’t enough.

Your devices need to actually use it as their DNS server.

The recommended approach is usually to configure your router’s DHCP service to distribute the Pi-hole IP address as the DNS server. Pi-hole’s documentation explains that this allows clients to use Pi-hole automatically without manually configuring every device.

For example:

Primary DNS:
192.168.1.50

where 192.168.1.50 is your Raspberry Pi.

Your router’s interface will vary by manufacturer.

Look for settings such as:

  • LAN
  • DHCP
  • DNS
  • Local Network
  • DHCP Server

Important: Don’t Configure a Random Secondary DNS

Be careful when configuring DNS.

For example, if you configure:

DNS 1: 192.168.1.50
DNS 2: 8.8.8.8

some clients may use the secondary DNS directly, potentially bypassing Pi-hole.

If your goal is network-wide filtering, make sure your network architecture is designed so clients consistently use Pi-hole.

Pi-hole’s documentation discusses different router configurations and ways to distribute Pi-hole through DHCP.

Step 10: Restart Your Devices

After changing DHCP/DNS settings, existing devices may still have their old DNS configuration.

You can:

  • Reconnect Wi-Fi
  • Restart the device
  • Renew its DHCP lease

Then verify that the device is using your Raspberry Pi as its DNS server.

Step 11: Check the Pi-hole Dashboard

Open:

http://192.168.1.50/admin/

You’ll see information such as:

  • Total queries
  • Blocked queries
  • Clients
  • Domains
  • Query types
  • Blocked domains

The dashboard makes it easy to see what is happening on your network.

How Pi-hole Blocks Ads

Suppose your phone requests:

ads.example.com

The DNS request goes to Pi-hole.

If the domain is on a blocking list:

Phone
  │
  ▼
Pi-hole
  │
  ├── Blocked → No connection
  │
  └── Allowed → Upstream DNS

This happens before the application connects to the destination.

That’s why Pi-hole can work beyond web browsers, including some applications and smart TVs.

Step 12: Test Pi-hole

From another computer, verify DNS resolution.

You can use:

nslookup example.com

or:

dig example.com

The DNS server shown in the output should correspond to your Pi-hole installation.

You can also watch DNS requests from the Pi-hole interface.

Check Pi-hole Status

The Pi-hole command-line utility provides a status command:

pihole status

The official CLI also includes commands for updating Pi-hole, repairing the installation, managing lists, and checking the installed version.

For example:

pihole version

Updating Pi-hole

Pi-hole provides an update command through its CLI.

You can check and update the installation with:

pihole -up

The current documentation also lists pihole updatePihole among the available commands.

Always review release notes before making significant changes to a production server.

Adding Custom Blocklists

Pi-hole’s filtering system can be customized.

You can manage:

  • Allowlists
  • Denylists
  • Regex rules
  • Wildcard rules
  • Groups

The current Pi-hole CLI supports commands such as:

pihole allow

and:

pihole deny

as well as regex and wildcard functionality.

Don’t add hundreds of random blocklists simply because they are available.

More lists aren’t necessarily better.

A poorly maintained list can cause legitimate websites or applications to stop working.

How to Allow a Blocked Domain

Sometimes Pi-hole will block something you actually need.

You can add a domain to the allowlist:

pihole allow example.com

Then reload your DNS lists if necessary.

You can also manage allowlists from the web interface.

How to Temporarily Disable Pi-hole

If you need to troubleshoot a website or application, you can temporarily disable blocking.

For example:

pihole disable 5m

This disables blocking for five minutes.

Pi-hole can automatically re-enable blocking after the specified period.

You can also re-enable it manually:

pihole enable

Pi-hole and IPv6

If your network uses IPv6, don’t forget to consider IPv6 DNS configuration.

Otherwise, some devices could potentially use an IPv6 DNS path that bypasses your Pi-hole IPv4 configuration.

The correct setup depends on your router and ISP.

For a simple home network, configure Pi-hole for IPv6 as appropriate rather than assuming that IPv4 DNS settings cover everything.

Should You Use Ethernet or Wi-Fi?

Ethernet is recommended.

Pi-hole doesn’t require much bandwidth, but Ethernet gives you:

  • Better reliability
  • Lower latency
  • No Wi-Fi dependency
  • More predictable connectivity

A wired Raspberry Pi is a better choice for infrastructure services such as DNS.

Can Pi-hole Run on a Raspberry Pi Zero?

Yes, Pi-hole is lightweight and supports ARM architectures including armv6, armv7, and armv8, provided the operating system is supported.

However, for a new installation I’d generally prefer a newer Raspberry Pi if you intend to run additional services.

A Raspberry Pi 4 or Raspberry Pi 5 gives you substantially more flexibility.

Can You Run Pi-hole and CasaOS Together?

Yes, but you need to think about how the services are deployed.

If you’re already using CasaOS as your home-server platform, Pi-hole can be deployed as a Docker application. Pi-hole provides official Docker documentation and a Compose-based deployment example.

However, DNS uses port 53, so you need to ensure another service isn’t already occupying that port.

For a dedicated Pi-hole installation, installing it directly on Raspberry Pi OS is often the simplest approach.

Pi-hole Bare Metal vs Docker

FeatureNative InstallationDocker
InstallationEasyEasy
IsolationLowerHigher
Port configurationSimplerMore configuration
Best for beginners⭐⭐⭐⭐⭐⭐⭐⭐⭐
CasaOS integrationNoExcellent
Resource usageVery lowVery low
Recommended for dedicated Pi-holeYesYes

Pi-hole officially documents both native installation and Docker deployment.

Troubleshooting Common Problems

Pi-hole dashboard doesn’t open

Check the Pi-hole status:

pihole status

Also verify the Raspberry Pi’s IP address:

hostname -I

Make sure you’re accessing the correct address.

DNS isn’t working

Check that Pi-hole is running:

pihole status

Then check whether another service is using port 53.

sudo ss -lntup | grep ':53'

Internet stops working after enabling Pi-hole

This usually indicates a DNS configuration problem.

Temporarily restore your router’s previous DNS settings and verify:

  1. Raspberry Pi is online.
  2. Pi-hole is running.
  3. Upstream DNS is configured.
  4. Port 53 is available.
  5. The router is distributing the correct Pi-hole IP.

Remember that if Pi-hole fails and your entire network depends on it for DNS, clients may lose name resolution.

Pi-hole Security Tips

Because Pi-hole becomes part of your network infrastructure, don’t expose its DNS or administration interface directly to the Internet.

Recommended practices:

  • Use a strong admin password.
  • Keep Raspberry Pi OS updated.
  • Keep Pi-hole updated.
  • Use Ethernet when possible.
  • Don’t expose port 53 to the public Internet.
  • Don’t expose the admin interface unnecessarily.
  • Use a VPN for remote administration.
  • Keep backups of important configuration.
  • Monitor unexpected DNS activity.

Pi-hole is intended primarily for network-wide DNS filtering, not as a public DNS server.

Advanced: Use Pi-hole with Tailscale or WireGuard

If you want to use your Pi-hole while away from home, a VPN can allow remote devices to send their DNS queries through your home network.

A typical architecture could look like:

Laptop / Phone
       │
   VPN Tunnel
       │
       ▼
 Raspberry Pi
       │
    Pi-hole
       │
       ▼
 Internet

This allows Pi-hole to provide filtering while you’re away from home without exposing its DNS service directly to the Internet.

Pi-hole vs Browser Ad Blockers

Pi-hole and browser extensions solve different problems.

FeaturePi-holeBrowser Blocker
Network-wide✅❌
Smart TVs✅Usually ❌
Mobile appsOftenLimited
Browser filteringGoodExcellent
Per-element filteringLimitedExcellent
Central management✅❌
Requires client installation❌✅

For the best experience, many users combine both.

Pi-hole provides network-level filtering while browser-based blockers can handle content-level filtering.

Pi-hole vs AdGuard Home

Another popular option is AdGuard Home.

Both provide network-wide DNS filtering.

FeaturePi-holeAdGuard Home
Raspberry Pi✅✅
DNS filteringExcellentExcellent
Web interfaceExcellentExcellent
Network-wide blocking✅✅
Docker✅✅
Custom rules✅✅
Raspberry Pi friendlyExcellentExcellent

If you’re already building your server around Pi-hole, there’s usually no reason to run both.

Is Pi-hole Worth Installing on a Raspberry Pi?

Yes.

Pi-hole is one of the most useful projects for an unused Raspberry Pi.

It’s:

  • Lightweight
  • Free
  • Open source
  • Easy to install
  • Useful across the entire network
  • Easy to monitor
  • Expandable

And because it requires so few resources, you can potentially use the same Raspberry Pi for other services if the hardware and configuration allow it.

Final Thoughts

Installing Pi-hole on a Raspberry Pi is one of the easiest ways to introduce network-wide DNS filtering to your home.

The installation itself is straightforward. The most important part is network configuration: give the Raspberry Pi a stable IP address and configure your router or DHCP server so clients use Pi-hole for DNS.

Once configured, you can manage filtering from the web dashboard, create custom rules, monitor DNS queries, and gradually expand your home server with other services.

If you’re already using CasaOS, Pi-hole is also a natural addition to a Raspberry Pi home server.

Frequently Asked Questions

Does Pi-hole block all ads?

No. Pi-hole blocks domains at the DNS level. It cannot block every type of advertisement, particularly content served from the same domain as legitimate content.

Does Pi-hole slow down the Internet?

It shouldn’t noticeably slow normal browsing. Pi-hole is lightweight and can cache DNS queries locally.

Does Pi-hole need a Raspberry Pi?

No. Raspberry Pi is simply one popular platform. Pi-hole supports several Linux distributions and architectures.

Does Pi-hole need a static IP?

Pi-hole needs a stable IP address. An actual static configuration isn’t mandatory; the official documentation specifically says a DHCP reservation is also acceptable.

Can Pi-hole run 24/7?

Yes. It is designed to be lightweight and suitable for continuous operation.

Can I use Pi-hole with Home Assistant?

Yes. They can run on the same home network and, depending on your hardware and deployment method, potentially on the same Raspberry Pi.

Related posts