Networking and Security

Pi-hole Install and Setup Guide (v6): Raspberry Pi, Ubuntu and Docker

Install Pi-hole v6 step by step on Raspberry Pi, Ubuntu or Docker: one-line installer, static IP, admin password, router DNS setup, pihole.toml and updates.

By Amjid Ali · · Updated · 5 min read

In this article
  1. Quick steps
  2. What changed in Pi-hole v6
  3. Pi-hole requirements
  4. Pi-hole setup on Raspberry Pi
  5. Install Pi-hole on Ubuntu Server
  6. Pi-hole on Docker
  7. After installing: Pi-hole setup steps
  8. How to upgrade Pi-hole
  9. Pi-hole troubleshooting
  10. Related guides

Prefer to watch? This video walks through it step by step. Prefer to read? The full guide is below.

To install Pi-hole, give a Linux machine a static IP and run curl -sSL https://install.pi-hole.net | bash. The installer sets up Pi-hole v6 in a few minutes on Raspberry Pi OS, Debian, Ubuntu, Fedora, CentOS Stream, Alpine or Armbian. Then open http://<pi-hole-ip>/admin, log in with the password the installer shows (change it with sudo pihole setpassword), and set your router's DHCP DNS server to the Pi-hole IP so every device on the network uses it. On any other system, run the official pihole/pihole Docker image.

Pi-hole is a network-wide DNS sinkhole: it blocks ads, trackers and malware domains for every device on your network, including smart TVs and phones, and shows statistics in its web interface. I have run it in my homelab for years. This guide is updated for Pi-hole v6 (Core v6.5, FTL v6.8 and Web v6.6.1 at the time of writing).

Quick steps

  1. Pick a device: Raspberry Pi, an Ubuntu or Debian VM, an LXC container or Docker.
  2. Give it a static IP (or a DHCP reservation on your router).
  3. Run the installer: curl -sSL https://install.pi-hole.net | bash.
  4. Open http://<ip>/admin and set the admin password.
  5. Point your router's DHCP DNS at the Pi-hole IP.
  6. Test, then keep it updated with pihole -up.

What changed in Pi-hole v6

If you followed an older guide, these are the big changes since v6 (released February 18, 2025):

  • Built-in web server and REST API in pihole-FTL. No more lighttpd or PHP.
  • One config file: /etc/pihole/pihole.toml replaces setupVars.conf, pihole-FTL.conf and most custom dnsmasq files. Change it in Settings in the web UI, or from the shell, for example sudo pihole-FTL --config dns.dnssec true.
  • HTTPS on port 443 with a self-signed certificate out of the box.
  • Docker variables use the FTLCONF_<section>_<key> format, for example FTLCONF_webserver_api_password.
  • Allowlist and denylist replace the old whitelist and blacklist names.

Pi-hole requirements

From the prerequisites page:

  • OS: a maintained version of Raspberry Pi OS, Debian, Ubuntu, Fedora, CentOS Stream, Alpine or Armbian (systemd or sysvinit).
  • Hardware: 512 MB RAM, at least 2 GB free storage (4 GB recommended). Any hardware works, not only a Pi.
  • Static IP address.
  • Ports: 53 TCP/UDP (DNS), 80 and 443 TCP (web interface, falls back to 8080/8443 if taken), 67 UDP only if you use Pi-hole's DHCP, 123 UDP only for its NTP server. Stop any other DNS server on port 53 first.

Pi-hole setup on Raspberry Pi

Works on any Raspberry Pi model (Pi Zero 2 W, 3, 4 or 5).

  1. Flash Raspberry Pi OS Lite with Raspberry Pi Imager. In the Imager settings, set a username and password, and enable SSH (the old pi/raspberry default login no longer exists).
  2. Boot the Pi, find its IP in your router and connect with ssh <user>@<ip>.
  3. Update it:
sudo apt update && sudo apt full-upgrade -y
  1. Give it a fixed address. The simplest way is a DHCP reservation for the Pi's MAC address in your router. Recent Raspberry Pi OS releases use NetworkManager, so if you prefer a static IP on the Pi itself, use sudo nmtui rather than editing /etc/dhcpcd.conf.
  2. Install Pi-hole:
curl -sSL https://install.pi-hole.net | bash

Accept the defaults unless you have a reason not to: choose an upstream DNS provider, keep the default blocklist, and turn on query logging if you want statistics. Note the admin password shown at the end. I have also used a Pi for other lab jobs, such as running Windows on a Raspberry Pi.

Install Pi-hole on Ubuntu Server

The same installer works on Ubuntu and Debian, bare metal, in a VM or in a Proxmox LXC container. Start from a fresh Ubuntu Server install with a static IP (set in netplan or as a DHCP reservation).

On Ubuntu, systemd-resolved runs a DNS stub listener on 127.0.0.53, and Pi-hole needs port 53 free. Before installing, check what is listening on port 53:

sudo ss -tulpn | grep ':53 '

Then install:

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

If you prefer to read the script before running it (the docs recommend checking it), download it first:

wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh

Pi-hole on Docker

Use the official pihole/pihole image. A compose.yaml based on the Pi-hole Docker docs:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
      - "443:443/tcp"
    environment:
      TZ: "America/New_York"
      FTLCONF_webserver_api_password: "change-this-password"
      FTLCONF_dns_listeningMode: "ALL"
    volumes:
      - ./etc-pihole:/etc/pihole
    cap_add:
      - NET_ADMIN
      - SYS_TIME
      - SYS_NICE
    restart: unless-stopped
docker compose up -d

FTLCONF_dns_listeningMode: "ALL" is needed with Docker's default bridge network. Add 67:67/udp only if Pi-hole will be your DHCP server. New to containers? See Docker for beginners.

After installing: Pi-hole setup steps

1. Log in to the web interface

Open http://<pi-hole-ip>/admin (or https://<pi-hole-ip>/admin and accept the self-signed certificate). To set or change the password:

sudo pihole setpassword

To run pihole CLI commands without the API password, add your user to the pihole group: sudo usermod -aG pihole $USER.

2. Point your network at Pi-hole

  • Best: in the router's LAN/DHCP settings, set the DNS server given to clients to the Pi-hole IP. Remove any secondary public DNS (such as 8.8.8.8), or devices will bypass Pi-hole.
  • If the router cannot change DNS: turn off the router's DHCP server and enable DHCP in Pi-hole under Settings > DHCP.
  • Last resort: set the DNS server manually on each device.

If you use pfSense, set the Pi-hole IP as the DNS server in the DHCP server settings, and use pfBlockerNG feeds on the firewall if you want blocking there as well.

3. Test it

nslookup doubleclick.net <pi-hole-ip>

A blocked domain returns 0.0.0.0. The dashboard should now show queries from your devices.

4. Optional: run your own recursive DNS

Pi-hole forwards queries to the upstream you chose. For more privacy, add Unbound as a local recursive resolver using the official Unbound guide.

How to upgrade Pi-hole

Check the installed versions:

pihole version

Update Core, Web and FTL in one go:

pihole -up

pihole -up is the short form of pihole updatePihole. In Docker, update by pulling the new image and recreating the container:

docker compose pull && docker compose up -d

Updating from v5 to v6 migrates your settings into pihole.toml automatically; take a backup first with Settings > Teleporter in the web interface.

Older pihole version output from a v5 install looked like this:

Pi-hole troubleshooting

  • FTL does not start, port 53 in use: another DNS server (systemd-resolved, dnsmasq, BIND) is listening. Find it with sudo ss -tulpn | grep ':53 ' and disable it.
  • Web interface on port 8080 instead of 80: another web server holds 80/443, so FTL fell back to 8080/8443. Stop it or change webserver.port in pihole.toml.
  • Ads still showing: the device uses another DNS (check for a secondary DNS on the router, browser DNS-over-HTTPS, or hard-coded DNS on some devices).
  • Lists not updating: run pihole -g to rebuild gravity.

Secure the rest of your network: my pfSense Network Security & Firewall Management course covers DNS, VLANs, VPNs and firewall rules for home and small business networks.

Frequently asked questions

How do I install Pi-hole?+

On a supported Linux system (Raspberry Pi OS, Debian, Ubuntu, Fedora, CentOS Stream, Alpine or Armbian) with a static IP, run curl -sSL https://install.pi-hole.net | bash and follow the installer. When it finishes, open http://<pi-hole-ip>/admin, log in with the password it shows (or set one with sudo pihole setpassword), then point your router's DHCP DNS setting at the Pi-hole IP.

What changed in Pi-hole v6?+

Pi-hole v6, released in February 2025, built the web server and a REST API into pihole-FTL, so lighttpd and PHP are no longer needed. Settings moved into a single TOML file, /etc/pihole/pihole.toml, which you can change in the web interface, with pihole-FTL --config, or with FTLCONF_ environment variables in Docker. HTTPS on port 443 with a self-signed certificate is built in.

What are the Pi-hole system requirements?+

Pi-hole needs at least 2 GB of free storage (4 GB recommended) and 512 MB of RAM, a supported operating system that uses systemd or sysvinit, and a static IP address (a DHCP reservation on your router is fine). Any hardware that runs a supported OS works, not only a Raspberry Pi.

How do I change the Pi-hole admin password?+

Run sudo pihole setpassword and enter a new password, or leave it empty to disable the password. In Docker, set the FTLCONF_webserver_api_password environment variable.

How do I set up my router to use Pi-hole?+

In your router's LAN or DHCP settings, set the DNS server handed to clients to the Pi-hole's IP address and remove any secondary public DNS such as 8.8.8.8, otherwise devices bypass Pi-hole. If the router cannot change DNS, disable its DHCP server and enable the DHCP server in Pi-hole instead.

How do I update Pi-hole?+

Run pihole -up on a normal install. It checks the Core, Web and FTL components and updates what is needed. In Docker, pull the new pihole/pihole image and recreate the container.

Sources

  1. Installation, Pi-hole documentation
  2. Prerequisites, Pi-hole documentation
  3. Post-Install, Pi-hole documentation
  4. The pihole command, Pi-hole documentation
  5. Pi-hole FTL configuration (pihole.toml), Pi-hole documentation
  6. Docker, Pi-hole documentation
  7. Pi-hole releases, GitHub

Related videos

Video library
  • Networking and Security

    Ad Blocking Setup: Pi-hole on Docker with pfSense Integration | Stop Ads Network-wide!

    · 6:21 · 1.8K views

    Watch on YouTube
  • Networking and Security

    Configuring pfSense as Upstream DNS for Pi-hole: Block Ads & Optimize Network Security

    · 9:03 · 9.7K views

    Watch on YouTube