Before running the Pi-hole Ubuntu Deploy installer, make sure your environment meets the requirements below. The Bash script is designed to be largely self-contained — it installs its own dependencies automatically — but it does expect a compatible hardware platform, a supported Ubuntu Server release, an active internet connection, and root-level access. Taking five minutes to verify these prerequisites now will prevent the most common installation failures.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.
Hardware
Pi-hole Ubuntu Deploy is intentionally lightweight and runs well on modest hardware. Any of the following platforms are suitable:- Virtual Machine — tested on VirtualBox (Host-Only and Bridged adapter modes) and compatible with other hypervisors.
- Raspberry Pi — any model with sufficient RAM is ideal for a dedicated, always-on deployment.
- Old PC or repurposed laptop — any x86-64 machine with a wired network interface works well.
| Resource | Minimum |
|---|---|
| RAM | 512 MB |
| CPU | 1 core |
| Disk | ~2 GB free (for OS, Pi-hole, and optional components) |
Operating System
The installer targets Ubuntu Server only. The following LTS releases are supported and tested:- Ubuntu Server 20.04 LTS (Focal Fossa)
- Ubuntu Server 22.04 LTS (Jammy Jellyfish)
- Ubuntu Server 24.04 LTS (Noble Numbat)
Network
An active internet connection is required during installation. The script needs to reach the Ubuntu package mirrors (apt), the official Pi-hole installer endpoint (install.pi-hole.net), the Internic root hints file, and optionally GitHub and Codeberg for PADD and the DNS Manager.
The project has been tested in two specific VirtualBox network configurations:
- Host-Only
- Bridged Adapter
Host-Only Adapter creates a private network between your host machine and the VM, completely isolated from your main LAN.Best for: Development and testing the installer via SSH from your host machine.Limitations:
- The VM cannot reach the internet directly through this adapter alone — you will need a second adapter (e.g. NAT) for internet access during installation.
- Pi-hole will not be reachable by other devices on your LAN; it can only serve DNS to the host machine.
- Not recommended as a production configuration for network-wide ad blocking.
192.168.56.0/24 (VirtualBox default).Access
The script must be executed with root privileges. Always run it usingsudo:
sudo will trigger an immediate error and exit:
Dependencies
You do not need to pre-install any dependencies. The script runsapt-get install automatically during Step 2 and installs everything it needs:
| Package | Purpose |
|---|---|
curl | Downloads the Pi-hole installer and other remote resources |
net-tools | Network interface utilities (ifconfig, etc.) |
ufw | Uncomplicated Firewall — configured automatically by the script |
sqlite3 | Injects blocklists directly into Pi-hole’s gravity database |
wget | Downloads PADD, root hints, and the Log2Ram signing key |
python3 | Required by the optional Python DNS Manager |
python3-venv | Creates an isolated virtual environment for the DNS Manager |
python3-pip | Installs Python dependencies (requests) for the DNS Manager |
git | Clones the DNS Manager source from Codeberg |