Pi-hole: Complete Install & Config Guide

Malware Domain Blocking

Blocks DNS resolution to known C2 infrastructure, phishing domains, and malware distribution hosts. Works across every device on the network including those you cannot install software on.

Full DNS Visibility

Every DNS query across your network is logged with timestamp, client IP, and resolution result. Useful for detecting suspicious lateral movement or beaconing behaviour from compromised hosts.

Tracker & Telemetry Suppression

Stops Windows telemetry, smart TV call-home traffic, and third-party trackers at the DNS layer — before a connection is established, not after.

Lightweight Footprint

Runs on a Raspberry Pi Zero 2 W (512 MB RAM). Handles thousands of DNS queries per second. Adds under 1 ms of latency for cached responses.

Download Raspberry Pi Imager from raspberrypi.com. Select Raspberry Pi OS Lite (64-bit) — no desktop needed. Before writing the image, click the gear icon (advanced options) and configure:

• a
  Enable SSH with password authentication or a pre-loaded public key.
• b
  Set your hostname (e.g. pihole.local), username, and password.
• c
  Configure Wi-Fi SSID and password if using wireless — wired Ethernet is strongly preferred for a DNS server.

Write the image to your SD card, insert it, power on the Pi, and wait approximately 90 seconds for first boot to complete.

Find the Pi's IP on your router's DHCP leases page or use a network scanner. SSH in with the credentials you set in Imager.

On Raspberry Pi OS Bookworm, network configuration uses nmcli (NetworkManager). Set a static IP on your active connection. Replace the example values with your network's details.

The official installer script handles all dependencies, installs the Pi-hole service, sets up the web interface, and configures dnsmasq as the DNS resolver backend.

If you prefer to inspect the script before running (recommended):

• 1
  Select network interface: choose eth0 for wired (recommended) or wlan0 for wireless.
• 2
  Select upstream DNS: choose Cloudflare (1.1.1.1), Quad9 (9.9.9.9), or Google (8.8.8.8). This can be changed after install.
• 3
  Install default blocklists: select Yes — this adds the StevenBlack hosts list as a starting point.
• 4
  Install Admin Web Interface: select Yes.
• 5
  Install lighttpd: select Yes — this is the web server for the admin panel.
• 6
  Enable query logging: select Yes. Logs are stored locally; configure retention below.
• 7
  Privacy level: select "Show everything" for full query logging, or a higher privacy mode if desired.

These commands install Docker Engine from Docker's official repository on Ubuntu or Debian. Skip if Docker is already installed.

Ubuntu 18.04+ and Debian 12 run systemd-resolved, which occupies port 53 on localhost. Pi-hole cannot bind to port 53 while this is active. You must disable it before starting the container.

Create a dedicated directory for Pi-hole's Docker deployment. The compose file below maps persistent volumes for the Pi-hole configuration and dnsmasq settings so your configuration survives container restarts and image updates.

Unlike bare-metal installs, Docker Pi-hole updates are done by pulling the latest image. Your configuration persists in the named volumes.

Minimum spec: 1 vCPU, 1 GB RAM, 10 GB disk. Use Ubuntu 22.04 LTS or 24.04 LTS (or Debian 12). Set the network adapter to Bridged mode — this gives the VM an IP on your LAN segment, making it reachable by all other devices.

• 1
  In VirtualBox: Settings → Network → Adapter 1 → Attached to: Bridged Adapter
• 2
  In VMware Workstation: VM Settings → Network Adapter → Bridged: Connected directly to the physical network
• 3
  In Proxmox: set the bridge to vmbr0 (or whichever bridge is on your LAN VLAN)
• 4
  In Hyper-V: use an External Virtual Switch connected to your LAN NIC

Ubuntu 22.04 and 24.04 both run systemd-resolved. This must be disabled before Pi-hole can bind to port 53. The procedure is identical to the Docker method above.

On Ubuntu 22.04/24.04, use Netplan to assign a static IP. Find your interface name first, then edit the Netplan config.

Identical to the Raspberry Pi install. The interactive installer detects Ubuntu and installs all required dependencies automatically.

Follow the same installer prompts as described in Phase 03, Step 4. Select your static interface (e.g. ens33), choose your upstream DNS, and enable the web interface. Note the admin password printed at the end.

The installer-generated password is random and long. Replace it with something you can remember — or keep it and store it in a password manager. Change via CLI:

The admin dashboard provides real-time query metrics. Key elements after logging in:

Navigate to Settings → DNS in the admin panel. Pi-hole ships with several upstream provider presets. The choice affects query privacy, DNSSEC support, and which threat feeds are available as upstream. DNSSEC is enabled by default on Quad9.

Navigate to Adlists in the sidebar. Add blocklist URLs — Pi-hole downloads these, deduplicates them, and imports them into the Gravity SQLite database. The curated Firebog lists are a well-maintained starting point used by most practitioners.

• 1
  StevenBlack Unified (included by default): https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts — ~220 K domains
• 2
  Hagezi Multi Pro: https://raw.githubusercontent.com/hagezi/dns-blocklists/main/hosts/pro.txt — ~600 K domains, high accuracy
• 3
  OISD Big: https://big.oisd.nl — 1 M+ domains, low false positive rate, actively maintained
• 4
  Malware domains (Firebog): https://malware-filter.gitlab.io/malware-filter/urlhaus-filter-hosts.txt — URLhaus active malware hosting domains
• 5
  Phishing Army: https://phishing.army/download/phishing_army_blocklist_extended.txt — active phishing domains updated daily

Blocklists will occasionally catch legitimate domains (false positives). Whitelist them immediately — blocked false positives break applications. Similarly, manually blacklist specific domains your chosen lists do not cover.

Log into your router's admin panel (typically 192.168.1.1 or 192.168.0.1). Find the DHCP server settings — the location varies by router brand:

Set DNS Server 1 to your Pi-hole's static IP (e.g. 192.168.1.50). Leave DNS Server 2 blank or set it to a fallback (e.g. 9.9.9.9) — if you set a fallback, devices will bypass Pi-hole when it is unreachable. For full enforcement, leave the secondary blank and ensure Pi-hole runs with restart: unless-stopped.

For devices on networks you do not control (corporate Wi-Fi), or for testing Pi-hole on a single machine, set DNS manually on the device:

After configuring your router, reconnect a client device and confirm queries are routing through Pi-hole.

In the Pi-hole admin Query Log, you should now see queries arriving from multiple client IPs on your network, not just from the Pi-hole host itself.

Pi-hole can resolve custom hostnames for devices on your LAN — useful for accessing services by name instead of IP. Navigate to Local DNS → DNS Records in the admin panel.

• 1
  Click Add. Enter the domain (e.g. nas.home) and the target IP (e.g. 192.168.1.100).
• 2
  For subdomains, use Local DNS → CNAME Records to alias media.home → nas.home etc.
• 3
  Devices using Pi-hole as DNS can now reach http://nas.home without mDNS or hosts file entries.

Conditional forwarding allows Pi-hole to resolve device hostnames by asking your router for its DHCP leases. Without it, the Query Log shows client IPs but not hostnames. Enable it in Settings → DNS → Conditional Forwarding.

• 1
  Enable "Use Conditional Forwarding".
• 2
  Enter your local network CIDR: e.g. 192.168.1.0/24.
• 3
  Enter your router's IP address: e.g. 192.168.1.1.
• 4
  Enter your local domain name if you use one: e.g. home.lan (leave blank if you do not).

After enabling, reverse DNS lookups for LAN IPs are forwarded to your router, which resolves them to device hostnames. These appear in the Query Log and Top Clients views.

You can disable your router's DHCP server and let Pi-hole hand out IP addresses instead. This ensures every device on the network automatically uses Pi-hole for DNS — no router DHCP configuration needed. Navigate to Settings → DHCP → DHCP Server.

• 1
  In your router, disable the DHCP server.
• 2
  In Pi-hole: Settings → DHCP → Enable DHCP server. Set the range (e.g. 192.168.1.100 – 192.168.1.200) and gateway IP.
• 3
  Set the lease time to 24 hours for a home network, 8 hours for a high-turnover environment.
• 4
  Under DHCP → Static Leases, bind device MAC addresses to fixed IPs for servers and printers.

When an application breaks after deploying Pi-hole, the cause is almost always a false positive block. The Query Log is the fastest path to diagnosis.

• 1
  Open Tools → Query Log. Filter by the device's IP address.
• 2
  Look for domains marked Pi-holed (red) around the time the application broke.
• 3
  Click the domain → select "Whitelist" to add it immediately.
• 4
  Alternatively: use Tools → Whitelist to add domains in bulk.
• 5
  Flush DNS cache on the affected device and retest the application.