Home Lab Projects

How do I set up Pi-hole?

Set up Pi-hole by installing it on an always-on device, giving that device a static IP, pointing your router at it, and checking that ads are blocked.

On this page
  1. Before you start
  2. Step 1: Prepare the operating system
  3. Step 2: Install Pi-hole
  4. Step 3: Point your network at Pi-hole
  5. Step 4: Check that it works
  6. Useful commands
  7. Common problems
  8. Keep it private
  9. Next steps

To set up Pi-hole, install it on a device that stays on, give that device a fixed IP address and point your router’s DHCP DNS setting at it. Then check that a blocked domain returns 0.0.0.0. The steps below cover Raspberry Pi OS and other Linux systems, with a Docker option in the install step.

Before you start

  • Pick an always-on device. A Raspberry Pi, a spare Linux PC, a VM or a container host all work. For hardware choices, see is a Raspberry Pi 4 overkill for Pi-hole?.
  • Use wired Ethernet if you can. It gives more consistent DNS latency than Wi-Fi.
  • Set a static IP or a DHCP reservation. Do this in your router before you install. If the address changes, your whole network loses DNS.
  • Know your router’s admin login. You’ll need it in step 3.

Step 1: Prepare the operating system

On Raspberry Pi OS:

  1. Use Raspberry Pi Imager to write Raspberry Pi OS Lite (64-bit) to the microSD card.
  2. Set a username and password, and enable SSH, before you write the card.
  3. Boot the Pi, connect over SSH and update the system:
sudo apt update && sudo apt upgrade -y

On Ubuntu, systemd-resolved listens on port 53 by default, which keeps Pi-hole from serving DNS. In the [Resolve] section of /etc/systemd/resolved.conf, set DNSStubListener=no. Then restart the service with sudo systemctl restart systemd-resolved. Check that the host can still resolve names afterwards.

Step 2: Install Pi-hole

The official installer is a script. Download it and read it before you run it:

curl -sSL https://install.pi-hole.net -o pihole-install.sh
less pihole-install.sh
sudo bash pihole-install.sh

The installer supports Debian, Ubuntu, Raspberry Pi OS, Fedora and several other distributions. During setup, it asks you to:

  • Choose an upstream DNS provider. Common choices include Cloudflare, Google, Quad9 and OpenDNS. You can add Unbound later for recursive resolution.
  • Keep or change the default blocklist. The default is StevenBlack’s unified hosts list.
  • Decide on query logging. The dashboard and query search depend on it.
  • Note the admin password. Change it later with pihole setpassword. Pi-hole v5 used pihole -a -p, so check which version you’re running.

If you prefer Docker, the official image is pihole/pihole. Map port 53 for both TCP and UDP, map the web interface port, and keep the configuration in a volume so your settings survive upgrades.

Step 3: Point your network at Pi-hole

  • Set the router’s DHCP DNS. In your router’s LAN or DHCP settings, set Pi-hole’s IP address as the DNS server. Devices receive it when they next connect.
  • If the router won’t change DNS, turn off the router’s DHCP server and turn on Pi-hole’s DHCP server. Run only one DHCP server on the network.
  • For a quick test, set DNS on a single device instead.

Devices cache DNS results, so renew the DHCP lease or reboot a device before you test it.

Two other things can bypass Pi-hole:

  • Don’t add a public DNS server as a second server. Clients choose between servers, so some lookups skip Pi-hole.
  • Some routers advertise their own IPv6 DNS server. Devices may use it instead of Pi-hole, so check the router’s IPv6 settings.

Step 4: Check that it works

Open the admin page at http://<pi-ip>/admin. Once DNS points to Pi-hole, http://pi.hole/admin also works. You should see queries from your devices on the dashboard.

Then test a blocked domain from a computer on your network:

nslookup doubleclick.net <pi-ip>

A blocked domain should return 0.0.0.0.

Useful commands

  • pihole -up updates Pi-hole.
  • pihole -g updates the blocklists.
  • pihole -q <domain> searches the lists for a domain.
  • pihole status shows whether DNS is running.

Pi-hole v6 keeps its main configuration in /etc/pihole/pihole.toml. Where you can, make changes through the web interface or the command line.

Common problems

  • Ads still show on some devices. Browser DNS-over-HTTPS can bypass Pi-hole. Turn it off in the browser settings. Also check the device for old DNS settings, and renew its DHCP lease.
  • A site you need is blocked. Search for the domain with pihole -q, then allow it in the web interface.
  • DNS stops after a reboot. Confirm the Pi has a static IP, then check the service with pihole status.
  • YouTube and in-app ads still play. Those ads come from the same domains as the video, so DNS blocking can’t reliably separate them.

Keep it private

  • Never port-forward port 53 or the admin interface to the internet.
  • Review scripts before you pipe them into bash, or use the manual install method from the Pi-hole documentation.

Next steps

Once Pi-hole runs, you can connect it to Home Assistant to see blocking stats and a pause switch on your dashboard.

The complete guide to home lab projects

Self-Hosted Apps That Integrate With Home Assistant: Immich, Donetick and TeslaMate
Read the guide

Keep exploring

Guides from other topics

All topics →