How to Self-Host Pi-hole: Network-Wide Ad Blocking for Every Device on Your Network

How Pi-hole Works: DNS Sinkholing Explained

Every time you open a website or app, your device asks a DNS server: "What is the IP address for this domain?" Normally, this request goes to your ISP's DNS server or a public resolver like Google (8.8.8.8) or Cloudflare (1.1.1.1). Pi-hole inserts itself between your devices and that upstream DNS server.

When a device on your network asks "What is the IP address for ads.doubleclick.net?", Pi-hole checks the request against its blocklists. If the domain is on a blocklist, Pi-hole responds with a null address (0.0.0.0) instead of forwarding the request upstream. The device thinks the ad server does not exist, the connection attempt fails silently, and no ad loads. If the domain is not blocked, Pi-hole forwards the query to your upstream resolver and returns the real answer.

What Hardware Do You Need?

Pi-hole is extremely lightweight. It runs well on almost any Linux hardware, including hardware that would be considered obsolete for anything else.

Installation Method 1: Bare Metal (Raspberry Pi or Linux)

The official Pi-hole installer is a single curl command. It runs an interactive setup wizard that guides you through the configuration.

# Disable the systemd-resolved stub listener
sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved

# Verify port 53 is now free
sudo ss -tulpn | grep :53

# If no output appears, port 53 is free and ready for Pi-hole

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

pihole setpassword

Enter New Password (Blank for no password):
Confirm Password:
[✓] Password Correct

Installation Method 2: Docker Compose

The Docker method is recommended if you are running Pi-hole alongside other containers, or if you prefer a clean setup that is easy to update and remove.

sudo sed -i 's/#DNSStubListener=yes/DNSStubListener=no/' /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    restart: unless-stopped
    ports:
      - "53:53/tcp"     # DNS over TCP
      - "53:53/udp"     # DNS over UDP
      - "80:80/tcp"     # Web admin UI (HTTP)
      - "443:443/tcp"   # Web admin UI (HTTPS, self-signed cert)
      # Uncomment if you want Pi-hole to serve as your DHCP server:
      # - "67:67/udp"
    environment:
      TZ: "Europe/Istanbul"                          # your timezone
      FTLCONF_webserver_api_password: "YourPassword" # v6 password variable — NOT WEBPASSWORD
      FTLCONF_dns_listeningMode: "ALL"               # required for Docker bridge network
      # Upstream DNS servers (semicolon-separated):
      FTLCONF_dns_upstreams: "1.1.1.1;1.0.0.1"      # Cloudflare
      # Or use Quad9 for malware blocking:
      # FTLCONF_dns_upstreams: "9.9.9.9;149.112.112.112"
    volumes:
      - "./etc-pihole:/etc/pihole"    # config and databases
    cap_add:
      - NET_ADMIN    # required if using Pi-hole as DHCP server
      - SYS_TIME     # required if Pi-hole should set system time (NTP)
      - SYS_NICE     # optional: gives Pi-hole more CPU priority

docker compose up -d

# Wait 30-60 seconds for Pi-hole to fully start and download initial blocklists
# Then check the logs:
docker logs pihole

::: Starting pihole-FTL...
  [i] Pi-hole blocking is enabled
  [✓] Started Pi-hole FTL

Pointing Your Network to Pi-hole

Installing Pi-hole does not automatically make it your DNS server. You need to tell your network to use it. There are two approaches:

Option A: Configure your router (recommended)

Log into your router's admin interface and find the DHCP or LAN settings. Set the primary DNS server to your Pi-hole's IP address. Leave the secondary DNS field empty or enter the Pi-hole IP again. Do not enter a public DNS server like 8.8.8.8 as a secondary — if you do, devices that get errors from Pi-hole will fall back to Google DNS and bypass all blocking.

After saving, reconnect your devices (or wait for DHCP lease renewal) and DNS queries will flow through Pi-hole. You should start seeing queries appear in the Pi-hole dashboard within minutes.

Option B: Configure devices individually

If you cannot change your router's DNS settings (rental equipment, ISP lock), set the DNS server manually on each device you want to protect. This is the less convenient approach since it requires per-device configuration.

Choosing Blocklists: What to Add

Pi-hole comes pre-configured with StevenBlack's Unified Hosts list, which is a solid starting point. The community has developed several other well-maintained blocklists that significantly improve coverage. Here are the ones worth adding in 2026:

# OISD Basic (ads and trackers, very safe)
https://adguardteam.github.io/HostlistsRegistry/assets/filter_27.txt

# OISD Big (more comprehensive, still very safe)
https://big.oisd.nl

# URLHaus — active malware distribution domains
https://urlhaus.abuse.ch/downloads/hostfile/

# Phishing Army — phishing sites, updated daily
https://phishing.army/download/phishing_army_blocklist.txt

To add blocklists: log into the Pi-hole admin UI, go to Lists, paste the URL, click Add, then go to the Gravity page and click Update (or run pihole -g from the terminal). Pi-hole downloads and processes all lists into a single gravity.db database. The update process runs automatically on a schedule.

Dealing with False Positives: Whitelist Management

Occasionally Pi-hole blocks a domain that a legitimate website or app needs. This shows up as a broken feature (images not loading, login failing, app not connecting) rather than an obvious error message. The typical diagnostic process:

# Add domain to whitelist via CLI
pihole -w example.com

# Or from the admin UI: Domains → Add domain → select Allowlist

Accessing Pi-hole's Admin Interface Remotely

Pi-hole's admin UI runs on port 80 of your local server. When you are at home, you can access it directly at http://192.168.x.x/admin. When you are away from home, that address is not reachable.

A Localtonet HTTP tunnel gives Pi-hole's admin interface a stable public HTTPS URL so you can check your network stats, add whitelists, and manage blocklists from anywhere. The DNS service itself (port 53) stays on your local network — only the web admin interface gets the public URL.

chmod +x localtonet
sudo mv localtonet /usr/local/bin/
sudo localtonet authtoken YOUR_TOKEN

sudo localtonet --install-service --authtoken YOUR_TOKEN
sudo localtonet --start-service --authtoken YOUR_TOKEN

Essential Pi-hole Commands

Backup and Restore

Pi-hole stores all its important data in the /etc/pihole directory. The key file is gravity.db, a SQLite database that contains your blocklists, allowlists, custom domain entries, and query history.

The easiest backup method is the built-in Teleporter: Settings → Teleporter → Export. This creates a downloadable archive of your configuration that you can import on any Pi-hole instance. For Docker setups, backing up the ./etc-pihole volume directory achieves the same result.

# Create a backup archive of the Pi-hole configuration
sudo tar -czf pihole-backup-$(date +%Y%m%d).tar.gz /etc/pihole

# For Docker: backup the mounted volume
tar -czf pihole-backup-$(date +%Y%m%d).tar.gz ./etc-pihole

To restore: import the Teleporter archive via Settings → Teleporter → Import, or extract the backup archive to the original location and restart Pi-hole.

Troubleshooting Common Problems

Frequently Asked Questions