Networking and Security
Pi-hole Install and Setup Guide (v6): Raspberry Pi, Ubuntu and Docker
By Amjid Ali · · Updated · 5 min read
In this article
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
- Pick a device: Raspberry Pi, an Ubuntu or Debian VM, an LXC container or Docker.
- Give it a static IP (or a DHCP reservation on your router).
- Run the installer:
curl -sSL https://install.pi-hole.net | bash. - Open
http://<ip>/adminand set the admin password. - Point your router's DHCP DNS at the Pi-hole IP.
- 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.tomlreplacessetupVars.conf,pihole-FTL.confand most custom dnsmasq files. Change it in Settings in the web UI, or from the shell, for examplesudo 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 exampleFTLCONF_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).
- Flash Raspberry Pi OS Lite with Raspberry Pi Imager. In the Imager settings, set a username and password, and enable SSH (the old
pi/raspberrydefault login no longer exists). - Boot the Pi, find its IP in your router and connect with
ssh <user>@<ip>. - Update it:
sudo apt update && sudo apt full-upgrade -y
- 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 nmtuirather than editing/etc/dhcpcd.conf. - 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.portinpihole.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 -gto rebuild gravity.
Related guides
- Homelab guide: how to build a homelab
- pfSense vs OPNsense
- Proxmox VE beginner's guide (Pi-hole runs well in a small LXC container)
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
- Installation, Pi-hole documentation
- Prerequisites, Pi-hole documentation
- Post-Install, Pi-hole documentation
- The pihole command, Pi-hole documentation
- Pi-hole FTL configuration (pihole.toml), Pi-hole documentation
- Docker, Pi-hole documentation
- 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
Keep reading
Networking and SecurityStep-by-Step Guide to Installing Wazuh on Ubuntu Server 24.04Install Wazuh 4.14 on Ubuntu Server 24.04 with the official all-in-one assistant, open the right ports, add Linux and Windows agents and fix common errors. · 7 min read
Networking and SecurityHow to Secure Your External Drive with Password ProtectionLearn how to enhance your data security with step-by-step instructions on password protecting your external drive using BitLocker encryption. Whether you're on Windows 11 Professional or moving data across platforms, this guide ensures your information stays secure. Subscribe now for more tech tutorials and stay informed! · 1 min read
Networking and SecurityHow to use easy surf free WiFi in Philippines?If you want to know how to use easy surf free wifi you must follow the following 4 easy steps. To get access to free Internet. · 1 min read