Pihole installation guide

Table of Contents

Prerequisites

System requirements

A Raspberry Pi, Linux server, or virtual machine
Supported OS: Raspberry Pi OS, Ubuntu, Debian, Fedora, CentOS
Minimum 512MB RAM (2GB+ recommended)
Static IP address for your Pihole server
Root or sudo access

Before you begin

Update your system:

sudo apt update && sudo apt upgrade -y

Method 1: Automated script installation

Quick Installation (Recommended)

The easiest way to install Pihole is using the official automated installer.

Step 1: download and run the installer:

curl -sSL https://install.pi-hole.net | bashCode language: JavaScript (javascript)

Or if you prefer to review the script first:

wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.shCode language: JavaScript (javascript)

Step 2: follow the prompts

The installer will guide you through:

Network Interface Selection: Choose the network interface Pi-hole will use (usually eth0 for Ethernet or wlan0 for WiFi)
Upstream DNS Provider: Select your preferred DNS provider:
- Google (8.8.8.8, 8.8.4.4)
- OpenDNS (208.67.222.222, 208.67.220.220)
- Cloudflare (1.1.1.1, 1.0.0.1)
- Quad9 (9.9.9.9, 149.112.112.112)
- Custom
Blocklists: Confirm to use the default blocklists (recommended)
Admin Web Interface: Choose to install the web admin interface (recommended)
Web Server: Choose to install lighttpd web server (recommended)
Query Logging: Enable query logging (recommended for statistics)
Privacy Mode: Select your preferred privacy level

Step 3: note Your Login Information

At the end of installation, you’ll see:

Admin password (save this!)

Web interface URL (usually http://pi.hole/admin or http://YOUR_IP/admin)

To change the admin password later:

pihole -a -p

Method 2: manual installation

Okay this one’s a bit more complicated. If you are like me though, you don’t wanna skip it. I always do everything manually and compile my own stuff.

Step 1: install dependencies

On Debian/Ubuntu/Raspberry Pi OS:

sudo apt update
sudo apt install -y git curl wget dnsutils net-tools
sudo apt install -y lighttpd php-cgi php-common php-sqlite3 php-xml php-json php-intl
sudo apt install -y sqlite3 cron

On CentOS/Fedora: (i’d personally stick with Debian but you do you)

sudo yum update -y
sudo yum install -y git curl wget bind-utils net-tools
sudo yum install -y lighttpd lighttpd-fastcgi php php-common php-cli
sudo yum install -y sqlite cronie

Step 2: create Pihole user and directories

# Create pihole user
sudo useradd -r -s /usr/sbin/nologin pihole

# Create necessary directories
sudo mkdir -p /etc/pihole
sudo mkdir -p /opt/pihole
sudo mkdir -p /var/www/html/adminCode language: PHP (php)

Step 3: clone Pihole repository

cd /tmp
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
cd Pi-holeCode language: PHP (php)

Step 4: install the core components

# Copy scripts
sudo cp -r /tmp/Pi-hole/advanced/Scripts /opt/pihole/
sudo cp -r /tmp/Pi-hole/automated\ install/basic-install.sh /opt/pihole/

# Set permissions
sudo chmod +x /opt/pihole/Scripts/*.shCode language: PHP (php)

Optional: Install FTL (Faster Than Light) DNS Engine

# Download FTL binary
cd /tmp
wget https://github.com/pi-hole/FTL/releases/latest/download/pihole-FTL-$(uname -m)-linux-gnu

# Install FTL
sudo mv pihole-FTL-* /usr/bin/pihole-FTL
sudo chmod +x /usr/bin/pihole-FTLCode language: PHP (php)

Step 6: create configuration files

Create /etc/pihole/setupVars.conf:

sudo tee /etc/pihole/setupVars.conf > /dev/null <<EOF
PIHOLE_INTERFACE=eth0
IPV4_ADDRESS=192.168.1.100/24
IPV6_ADDRESS=
QUERY_LOGGING=true
INSTALL_WEB_SERVER=true
INSTALL_WEB_INTERFACE=true
LIGHTTPD_ENABLED=true
CACHE_SIZE=10000
DNS_FQDN_REQUIRED=true
DNS_BOGUS_PRIV=true
DNSMASQ_LISTENING=single
WEBPASSWORD=
BLOCKING_ENABLED=true
PIHOLE_DNS_1=8.8.8.8
PIHOLE_DNS_2=8.8.4.4
EOFCode language: JavaScript (javascript)

Note: Replace 192.168.1.100/24 with your static IP and subnet, and eth0 with your network interface.

Step 7: configure dnsmasq

Create /etc/dnsmasq.d/01-pihole.conf:

sudo tee /etc/dnsmasq.d/01-pihole.conf > /dev/null <<EOF
addn-hosts=/etc/pihole/gravity.list
addn-hosts=/etc/pihole/black.list
addn-hosts=/etc/pihole/local.list

domain-needed
bogus-priv
no-resolv

server=8.8.8.8
server=8.8.4.4

interface=eth0
bind-interfaces

cache-size=10000
log-queries
log-facility=/var/log/pihole.log

local-ttl=2

conf-file=/etc/dnsmasq.d/02-pihole-dhcp.conf
conf-file=/etc/dnsmasq.d/05-pihole-custom-cname.conf
EOFCode language: JavaScript (javascript)

Step 8: set up gravity (blocklist db)

# Create initial gravity database
sudo touch /etc/pihole/gravity.list
sudo touch /etc/pihole/black.list
sudo touch /etc/pihole/whitelist.txt
sudo touch /etc/pihole/regex.list

# Set ownership
sudo chown -R pihole:pihole /etc/piholeCode language: PHP (php)

Step 9: configure web interface

# Clone web interface
cd /var/www/html
sudo git clone --depth 1 https://github.com/pi-hole/AdminLTE.git admin

# Set permissions
sudo chown -R www-data:www-data /var/www/htmlCode language: PHP (php)

Configure lighttpd —> create /etc/lighttpd/conf-available/15-pihole-admin.conf:

sudo tee /etc/lighttpd/conf-available/15-pihole-admin.conf > /dev/null <<EOF
\$HTTP["url"] =~ "^/admin/" {
    setenv.add-response-header = (
        "X-Pi-hole" => "The Pi-hole Web interface is working!",
        "X-Frame-Options" => "DENY"
    )
}

\$HTTP["url"] == "/admin" {
    url.redirect = ("" => "/admin/")
}
EOFCode language: PHP (php)

Enable the configuration:

sudo ln -s /etc/lighttpd/conf-available/15-pihole-admin.conf /etc/lighttpd/conf-enabled/
sudo lighttpd-enable-mod fastcgi
sudo lighttpd-enable-mod fastcgi-php
sudo service lighttpd restart

Step 10: Create Systemd Service for FTL

Create /etc/systemd/system/pihole-FTL.service:

sudo tee /etc/systemd/system/pihole-FTL.service > /dev/null <<EOF
[Unit]
Description=Pi-hole FTL
After=network.target

[Service]
Type=forking
ExecStart=/usr/bin/pihole-FTL
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOFCode language: JavaScript (javascript)

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable pihole-FTL
sudo systemctl start pihole-FTL

Step 11: set up the pihole command

# Create symlink for pihole command
sudo ln -s /opt/pihole/Scripts/pihole /usr/local/bin/pihole
sudo chmod +x /usr/local/bin/piholeCode language: PHP (php)

Step 12: update gravity (download blocklists)

pihole -g

and set admin password:

pihole -a -p

Post-Installation Configuration

1. Access the Web Interface

Navigate to:

http://pi.hole/admin or
http://YOUR_SERVER_IP/admin

2. Configure Your Router

Set your router’s DNS server to your Pi-hole’s IP address. This varies by router, but typically:

Log into your router’s admin interface
Find DHCP or DNS settings
Set Primary DNS to your Pi-hole’s IP (e.g., 192.168.1.100)
Set Secondary DNS to a fallback (e.g., 8.8.8.8) or leave blank for Pi-hole only
Save and reboot the router

3. Configure Individual Devices (Alternative)

If you don’t want to change router settings, configure DNS on each device:

Windows:

Network Settings —> Change adapter options → Right-click adapter → Properties
Select “Internet Protocol Version 4 (TCP/IPv4)” → Properties
Use the following DNS server addresses: Enter your Pi-hole IP

macOS:

System Preferences → Network → Advanced → DNS
Add your Pi-hole IP using the + button

Linux:

Edit /etc/resolv.conf or use NetworkManager

iOS/Android:

WiFi Settings → Configure DNS → Manual → Add Server

4. Add Additional Blocklists

In the web interface:

Go to “Group Management” → “Adlists”
Add blocklist URLs (search for “pihole blocklists” for community recommendations)
Update gravity: pihole -g

Popular blocklist sources:

5. Whitelist/Blacklist Domains

Via Web Interface:

Tools → Query Log (to find domains to whitelist)
Blacklist/Whitelist → Add domains

If you wanna do this via cmd:

# Whitelist
pihole -w example.com

# Blacklist
pihole -b ads.example.com

# Regex whitelist
pihole --regex-whitelist ".*\.example\.com$"

# Regex blacklist
pihole --regex-blacklist "^ad[sx]?[0-9]*\."Code language: PHP (php)

Set Up Local DNS Records

Add local DNS entries for devices on your network:

# Edit local DNS file
sudo nano /etc/pihole/custom.list

# Add entries in format: IP_ADDRESS HOSTNAME
192.168.1.10 myserver.local
192.168.1.20 printer.localCode language: PHP (php)

and then restart:

pihole restartdns

Troubleshooting

Pihole Not Blocking Ads?

Check DNS is pointing to Pi-hole:

nslookup pi.holeCode language: CSS (css)

2. Verify FTL is running:

sudo systemctl status pihole-FTL

3. Check gravity database:

pihole -g

4. Flush DNS cache on client devices

Web Interface Not Accessible

Check lighttpd status:

sudo systemctl status lighttpd

2. Restart lighttpd:

sudo systemctl restart lighttpd

3. Check firewalls

sudo ufw allow 80/tcp
sudo ufw allow 53/tcp
sudo ufw allow 53/udp

DNS Resolution issues

Check upstream DNS servers:

pihole -c -e

2. Test DNS resolution

dig @127.0.0.1 google.comCode language: CSS (css)

3. Check dnsmasq configuration:

pihole-FTL dnsmasq-test

Reset admin password:

pihole -a -p

Update pihole:

pihole -up

Wanna uninstall it? Well you can but what would be the point of this whole ass blog post?

-_-

fine.

pihole uninstall

View logs:

# Real-time query log
pihole -t

# FTL log
sudo cat /var/log/pihole-FTL.log

# Web server log
sudo cat /var/log/lighttpd/error.logCode language: PHP (php)

Check pihole status:

pihole status

Restart pihole services:

# Restart DNS
pihole restartdns

# Restart FTL
sudo systemctl restart pihole-FTL

# Restart web server
sudo systemctl restart lighttpdCode language: PHP (php)

Useful commands

# Update gravity (blocklists)
pihole -g

# Enable/disable blocking
pihole enable
pihole disable [time]

# Tail the query log
pihole -t

# Check version
pihole -v

# Update Pi-hole
pihole -up

# Reconfigure
pihole -r

# Uninstall
pihole uninstall

# Debug
pihole -d

# Whitelist/Blacklist
pihole -w domain.com
pihole -b domain.com

# Query database
pihole -q domain.com

# Chronometer (live stats)
pihole -cCode language: PHP (php)

Additional Resources

Official Documentation: https://docs.pi-hole.net/
Discourse Forum: https://discourse.pi-hole.net/
GitHub: https://github.com/pi-hole/pi-hole
Reddit: r/pihole

! Note !: Always ensure you have a backup DNS solution in case Pi-hole goes down. Consider setting up a secondary Pi-hole or having a backup DNS server configured on critical devices.

Hello Cro Crow GIFfrom Hello Cro GIFs

If you made it to the end, comment “pizza”.

Thank you cro 🤝