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:
- Use Raspberry Pi Imager to write Raspberry Pi OS Lite (64-bit) to the microSD card.
- Set a username and password, and enable SSH, before you write the card.
- 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 usedpihole -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 -upupdates Pi-hole.pihole -gupdates the blocklists.pihole -q <domain>searches the lists for a domain.pihole statusshows 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.