Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/damianiglesias/pihole-ubuntu-deploy/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the fastest path to a working Pi-hole v6 installation using the Pi-hole Ubuntu Deploy Bash script. In roughly ten to fifteen minutes — mostly spent waiting on package downloads — you’ll have a fully configured network-wide DNS ad blocker with a static IP, a hardened firewall, and an optional suite of extras. No manual configuration files, no copy-pasting commands from a wiki: one script handles everything interactively.
1

Clone the Repository

Clone the project from GitHub and change into the project directory:
git clone https://github.com/damianiglesias/pihole-ubuntu-deploy && cd pihole-ubuntu-deploy
2

Run the Installer

The script must be executed as root. Launch it with sudo:
sudo ./deploy.sh
The installer opens with a blue ASCII banner and version stamp confirming you’re running the correct release:
  ____  _       _           _
 |  _ \(_)     | |         | |
 | |_) |_      | |__   ___ | | ___
 |  __/| |_____| '_ \ / _ \| |/ _ \
 | |   | |_____| | | | (_) | |  __/
 |_|   |_|     |_| |_|\___/|_|\___|
             INSTALLER v4.1
If you see ERROR: Please run as root (sudo ./deploy.sh), you forgot the sudo prefix — re-run the command with it.
3

Network Preparation (Automatic)

Step 1 runs automatically without any input from you. The script:
  1. Stops and disables systemd-resolved to free port 53 for Pi-hole.
  2. Replaces /etc/resolv.conf with temporary entries pointing to 8.8.8.8 and 1.1.1.1.
  3. Pings 8.8.8.8 to verify internet connectivity before proceeding.
If the ping fails, the script exits with a fatal error and advises you to check your VirtualBox network adapter settings (try NAT or Bridged mode). Fix your network and re-run.
4

Install Dependencies (Automatic)

Step 2 runs apt-get update followed by a single install command for all required packages — no interaction needed:
curl  net-tools  ufw  sqlite3  wget  python3  python3-venv  python3-pip  git
If apt-get update fails (e.g. because the network isn’t fully ready), the script exits with an error. Wait a moment and re-run.
5

Install Pi-hole v6

Step 3 launches the official Pi-hole installer by piping the install script directly into bash:
curl -sSL https://install.pi-hole.net | bash
Press Enter when prompted, then work through the Pi-hole installer’s blue TUI screens. Accept all defaults unless you have a specific reason to change them — the deploy script configures everything that matters (blocklists, password, firewall, static IP) in the steps that follow.After the installer completes, the script verifies the pihole command is available. If it isn’t, installation failed and you’ll need to check the output above for errors.
6

Install Advanced Blocklists (Optional)

After Pi-hole installs, you’re prompted to inject three curated blocklists directly into Pi-hole’s SQLite gravity database:
Install Advanced Lists? [y/n]:
Entering y injects the following lists and immediately runs pihole -g to rebuild the gravity database:
ListSourceFocus
StevenBlack Unified Hostsraw.githubusercontent.com/StevenBlack/hostsAds, malware, fakenews, gambling
AdGuard Mobilev.firebog.net/hosts/AdguardDNS.txtMobile ads and trackers
EasyPrivacy Trackingv.firebog.net/hosts/Easyprivacy.txtTracking and telemetry
Enter n to skip and use Pi-hole’s default blocklists only.
7

Set the Admin Password

Step 4 prompts you to set the Pi-hole web admin password. You’ll be asked to type and then confirm your chosen password (input is hidden):
> Password:
> Confirm:
The script loops until both entries match and neither is empty. Once confirmed, the password is applied via pihole setpassword and pihole-FTL is restarted. Keep this password safe — you’ll need it to log into the web interface at http://<your-ip>/admin.
8

Install Optional Components

The script walks you through four optional add-ons, each with its own [y/n] prompt:
ComponentPromptWhat it does
UnboundInstall Unbound? [y/n]Installs a local recursive DNS resolver on 127.0.0.1:5335. After install, point Pi-hole’s upstream DNS to 127.0.0.1#5335 in the web interface.
PADDInstall PADD dashboard? [y/n]Installs the Pi-hole terminal dashboard to /usr/local/bin/padd. A follow-up prompt offers to auto-start it on SSH login.
DNS ManagerInstall DNS Manager tool? [y/n]Clones the Python DNS Manager from Codeberg into /opt/pihole-dns-manager, creates a virtualenv, and generates a run_dns_sync.sh wrapper.
Log2RamInstall Log2Ram? [y/n]Adds the Azlux apt repository and installs Log2Ram to redirect Pi-hole’s log writes to RAM, reducing disk wear. Takes effect after the next reboot.
Unbound is currently experimental. It installs successfully but may require additional manual configuration to work correctly with Pi-hole. See Unbound DNS for details.
9

Configure a Static IP

Step 6 lists your available network interfaces and asks you to select one:
Type interface name (e.g. enp0s8):
After you enter the interface name, the script detects its current IP and default gateway, displays them, and asks:
Set this IP as STATIC? [y/n]:
Entering y writes a Netplan configuration file to /etc/netplan/99-pihole-static.yaml and runs netplan apply. Your existing Netplan files are backed up to /etc/netplan/backup/ before any changes are made.Setting a static IP is strongly recommended so your router always knows where to send DNS queries.
10

Deployment Complete — Final Report

Once all steps finish, the terminal clears and the final report is displayed. Note the server IP and web interface URL — you’ll need them to configure your router and to access the Pi-hole admin panel.

​
Final Report Output

When the script completes successfully, you’ll see a green banner followed by your connection details: 
################################################
#             DEPLOYMENT SUCCESSFUL!           #
################################################

 Server IP:      192.168.1.50
 Web Interface:  http://192.168.1.50/admin

 PASSWORD:       your-admin-password

 UNBOUND INSTRUCTIONS:
   1. Login to Web Interface -> Settings -> DNS
   2. Uncheck 'Google' & Check 'Custom 1': 127.0.0.1#5335

 PADD: Type padd to view dashboard.
   (ENJOY!)
The Server IP is the address to use as your router’s primary DNS server. The Web Interface URL opens the Pi-hole admin dashboard in any browser on your LAN.
To enable network-wide ad blocking for all devices, log into your router’s admin panel and set its Primary DNS server to the Pi-hole server IP shown in the final report. Most home routers expose this under DHCP settings or WAN/Internet settings. Once saved, any device that gets its IP from your router via DHCP will automatically use Pi-hole for DNS.

​
Next Steps

  • Read the Bash Script deployment guide for a detailed breakdown of every step, configuration option, and troubleshooting tip.
  • Prefer a containerised setup? See the Ansible + Docker guide to deploy Pi-hole in Docker using an Ansible playbook instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us