Skip to content
Edward Angert
Blog

Pi-hole v6 Setup Guide

Pi-hole is a DNS-based ad blocker for your whole network.

A basic way to understand it is:

When a device on your network tries to access something from the Internet, it checks in with the Pi-hole first. The Pi-hole checks the address of what the device is looking for against a list you’ve configured the Pi-hole with, and if that resource isn’t on the list, it allows the device to connect to it.

Usually, the website itself still loads while the ads and trackers get blocked.

Pi-hole dashboard

Due to some hardware issues in the past, I’ve had to rebuild this setup several times, collecting steps from around the Internet each time. This guide is a collection of my notes, organized into documentation to help other people set up or rebuild their Pi-hole.

The steps in this guide document how I set up Pi-hole v6 with:

  • Raspberry Pi running Raspberry Pi OS (Bookworm)
  • UFW firewall
  • HaGeZi tiered blocklists with supplementary category lists
  • Allowlists for streaming and smart TV platforms
  • Omada controller DHCP configured for network-wide blocking
  • Optional:
    • Teleporter backup for configuration export/restoration
    • Unbound recursive DNS with Cloudflare as fallback
    • Netdata system and Pi-hole monitoring
    • Tailscale for remote admin access and to make the Pi-hole act as a personal VPN
    • More restrictive groups for specific devices

Visit the official Pi-hole documentation for more use cases and details.

This guide is written for Pi-hole v6. It’s meant to be an opinionated copy-and-paste solution that a relative novice can follow from beginning to end or use as a reference.

If you have Pi-hole v5 installed, many of the concepts remain the same in v6. You can still access the older version of this guide on GitHub.

If you identify any errors or areas for improvement, please submit a GitHub issue or select Edit page at the bottom of any page to suggest a change.

Prerequisites

Section titled “Prerequisites”
  • Access to your router’s configuration.

    • This is required if you want devices on your network to use the Pi-hole.

    • Some routers have a sticker with their admin information. You can also try some common router IPs like 192.168.1.1.

      This is usually your gateway IP.

  • Raspberry Pi
  • microSD card, 8 GB or larger, with a way to plug it into your computer.
  • Familiarity with a terminal and the command line, or at least comfort following terminal commands. Most commands in this guide can be copied and pasted, and I try to explain the ones that can’t be.

Before You Begin

Section titled “Before You Begin”

The Add Blocklists and Allowlists page covers a curated set of community-maintained lists, including options for advertisements, malware, phishing, social media, gambling, and NSFW content. Pi-hole is great at blocking domains like these.

A few limitations to consider before you start:

Pi-hole works at the DNS level (DNS Reddit ELI5). It sees (and can log) the domain name but not the URL or content. That means it can’t distinguish between types of content on the same domain. Something like youtube.com is either blocked entirely or not at all because Pi-hole can’t tell the difference between kids content and anything else.

Some streaming services also serve ads through the same domains as their content. Pi-hole cannot block Hulu or Disney+ ads on their ad-supported plans without breaking the service.

For most other services, you can add service-specific rules to the allowlists when you get to that page, or skip ahead if that’s your main Pi-hole use case.

In This Guide

Section titled “In This Guide”