Step-by-Step: Install and Configure Pi-hole with the Proxmox Community Script#

This guide covers a full technical setup for Pi-hole on Proxmox using the Community Scripts installer.

It includes:

  • creating the Pi-hole LXC
  • assigning a static IP
  • verifying DNS is working
  • configuring your router, ISP modem, or firewall DHCP server to hand out Pi-hole as DNS
  • fallback options when your ISP equipment does not allow custom DNS
  • post-install Pi-hole configuration
  • basic validation and troubleshooting

What this guide assumes#

You have:

  • a working Proxmox VE host
  • shell access to the Proxmox host
  • a LAN subnet such as 192.168.1.0/24
  • a router or firewall acting as the default gateway

Example values used in this guide:

  • Gateway: 192.168.1.1
  • Pi-hole IP: 192.168.1.10
  • DHCP range: 192.168.1.100 to 192.168.1.200
  • Subnet mask: 255.255.255.0

Adjust the examples to match your network.

Network design before you start#

Before installing Pi-hole, choose the IP settings now.

  • Put Pi-hole on a static IP
  • Keep that IP outside your DHCP pool
  • Let your router or firewall DHCP server hand out Pi-hole as the DNS server

Example:

Gateway / Router: 192.168.1.1
Pi-hole:          192.168.1.10
DHCP Pool:        192.168.1.100 - 192.168.1.200
Subnet:           192.168.1.0/24

1. Install Pi-hole using the Community Script#

Open a shell on your Proxmox host and run:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"

The script will launch an interactive wizard and create an LXC container for Pi-hole.

2. Choose the LXC settings during the installer#

During the script prompts, use these recommendations unless you have a reason to change them.

Suggested settings#

  • Container type: default generated by the script
  • Hostname: pihole
  • IP address: static, for example 192.168.1.10/24
  • Gateway: 192.168.1.1
  • DNS during install: leave at defaults unless your environment requires something specific
  • Unbound: enable it if you want Pi-hole to use a local resolver

If the installer asks for DHCP instead of static networking, do not use DHCP unless you are also creating a reservation for the container. Pi-hole should not move to a different IP.

3. Start the container and confirm its IP#

After the script finishes, note the CTID of the new container.

Check container status:

pct list

You can also inspect the network configuration:

pct config <CTID>

Replace <CTID> with the actual container ID.

Example:

pct config 105

Look for the network line, which should show the static IP configuration.

4. Open the Pi-hole web interface#

From a browser on your LAN, open:

http://192.168.1.10/admin

Replace the IP with your Pi-hole container IP.

If the page does not load:

  • verify the container is running
  • verify the IP address is correct
  • verify your Proxmox bridge is connected to the correct LAN

5. Set the Pi-hole admin password#

Enter the container shell from the Proxmox host:

pct enter <CTID>

Then set the admin password:

pihole setpassword

You can also set it directly:

pihole setpassword YourStrongPasswordHere

Once complete, log in to the web UI.

6. Verify Pi-hole is answering DNS before changing DHCP#

Do not change the network DNS for all devices until you confirm Pi-hole is actually resolving queries.

From another machine on your LAN, test with nslookup:

nslookup google.com 192.168.1.10

Or test with dig:

dig @192.168.1.10 google.com

A successful test should return a normal DNS answer section.

To verify blocking later, test against a known ad domain after blocklists are loaded:

nslookup doubleclick.net 192.168.1.10

7. Configure the network to use Pi-hole as DNS#

This is the key integration step.

There are three common ways to do it:

  1. configure your firewall or router DHCP server to hand out Pi-hole as DNS
  2. configure your ISP modem/router to hand out Pi-hole as DNS
  3. disable router DHCP and let Pi-hole provide DHCP

Best practice#

Use one of your own routers or firewalls as DHCP if possible, and configure that DHCP server to advertise Pi-hole.

8. Option A: Configure your firewall or router DHCP server#

If you use pfSense, OPNsense, OpenWrt, UniFi, MikroTik, or another router with configurable DHCP options, update the DHCP scope.

DHCP values to use#

  • Gateway / Router: 192.168.1.1
  • DNS server: 192.168.1.10
  • DHCP range: your existing client pool, for example 192.168.1.100 - 192.168.1.200

Important recommendation#

Do not set a public resolver such as 8.8.8.8 or 1.1.1.1 as the secondary DNS if you want reliable Pi-hole filtering. Many client devices will bypass Pi-hole whenever a second resolver is available.

After changing DHCP#

Renew the DHCP lease on clients.

Examples:

Windows#

ipconfig /release
ipconfig /renew

Linux with NetworkManager#

nmcli connection down <connection-name>
nmcli connection up <connection-name>

Linux with dhclient#

sudo dhclient -r
sudo dhclient

macOS#

Disable and re-enable the network interface, or renew the DHCP lease from network settings.

9. Option B: Configure your ISP modem/router DHCP DNS settings#

If your ISP modem/router exposes DHCP or LAN DNS options, find the LAN settings page and set:

  • Primary DNS: 192.168.1.10
  • Secondary DNS: blank, or a second Pi-hole if you have one

Typical menu locations:

  • LAN
  • Local Network
  • DHCP Server
  • DNS Server
  • Home Network

If the modem/router allows it#

Save the changes and renew DHCP leases on clients.

If the modem/router does not allow changing DNS#

Continue to the fallback methods below.

10. Fallback A: Disable router DHCP and let Pi-hole serve DHCP#

This is the most common workaround when ISP equipment is locked down.

Step 1: Disable DHCP on the modem/router#

Open the router or ISP modem admin page and disable its DHCP server.

Do not proceed until you are ready to immediately enable DHCP elsewhere.

Step 2: Enable DHCP in Pi-hole#

In the Pi-hole web UI:

  • go to Settings
  • open DHCP
  • enable DHCP server

Use values like:

  • Range start: 192.168.1.100
  • Range end: 192.168.1.200
  • Router (gateway): 192.168.1.1
  • Domain name: optional, for example home.lan

Save the settings.

Step 3: Renew client leases#

Reboot clients or renew DHCP leases so they begin receiving addresses from Pi-hole.

Warning#

Only one DHCP server should be active on the subnet. Running both the router DHCP server and Pi-hole DHCP at the same time will cause conflicts.

11. Fallback B: Set DNS manually on selected devices#

If you cannot change DHCP and do not want Pi-hole to run DHCP, you can manually point specific devices at Pi-hole.

Set the device DNS server to:

192.168.1.10

This works well for:

  • desktops
  • laptops
  • test devices
  • media boxes
  • servers

This is useful for validation, but it does not scale well.

12. Fallback C: Put the ISP modem in bridge mode and use your own firewall#

This is the cleanest long-term architecture.

Resulting design#

  • ISP modem in bridge mode
  • your own firewall or router handles NAT, DHCP, and LAN DNS settings
  • that DHCP server advertises Pi-hole to clients
  • no need to use a Pi-hole

This is the best option when you want full control over:

  • DNS
  • VLANs
  • reservations
  • firewall rules
  • DNS redirection

13. Optional enforcement: Redirect all standard DNS traffic to Pi-hole#

If you manage your own firewall, you can force devices that try to use outside DNS servers back to Pi-hole.

Use case#

Some clients ignore DHCP-provided DNS and try to use:

  • 8.8.8.8
  • 1.1.1.1
  • ISP DNS

Firewall idea#

Create a NAT redirect or DNS interception rule so that outbound traffic on port 53 is redirected to:

192.168.1.10:53

Limitation#

This only affects standard DNS on port 53. It does not automatically stop:

  • DNS over HTTPS
  • DNS over TLS
  • app-embedded encrypted DNS

14. Initial Pi-hole configuration after install#

Once clients can reach the Pi-hole UI, complete the following configuration tasks.

14.1 Configure the upstream DNS resolver#

Open:

  • Settings
  • DNS

Choose one of these designs.

Option 1: Use Unbound#

If you enabled Unbound during the Community Script install, configure Pi-hole to use that local resolver.

This is the preferred setup for many home labs because it keeps DNS local and avoids depending entirely on a public resolver.

Option 2: Use a public upstream resolver#

If you did not install Unbound, choose a public resolver such as:

  • Cloudflare
  • Quad9
  • Google
  • OpenDNS

Choose one consistent upstream and test it before adding more complexity.

14.2 Update gravity#

From inside the container, update the gravity database:

pihole -g

14.3 Review blocklists#

In the Pi-hole UI, review the default adlists first.

Recommended approach:

  • start with defaults
  • validate streaming apps, IoT devices, and mobile devices
  • add specialty lists later only if you have a reason

14.4 Configure local DNS records#

For important devices, add local DNS names.

In the Pi-hole UI:

  • go to Local DNS
  • choose DNS Records

Example entries:

proxmox.home.arpa   -> 192.168.1.2
nas.home.arpa       -> 192.168.1.20
pihole.home.arpa    -> 192.168.1.10
router.home.arpa    -> 192.168.1.1

This allows you to access services by name rather than IP.

14.5 Configure local CNAMEs if needed#

If you want friendlier hostnames for services behind another IP, use Local CNAME Records.

Example:

grafana.home.arpa -> proxmox.home.arpa

14.6 Configure conditional forwarding if your router supports local hostname resolution#

If your router or firewall holds DHCP lease hostnames, enable Conditional Forwarding in Pi-hole.

Use values like:

  • Local network: 192.168.1.0/24
  • Router IP: 192.168.1.1
  • Local domain: home.arpa or your local domain

This can make Pi-hole show client names instead of only IP addresses.

14.7 Review the query log#

Open Query Log and check:

  • client devices are reaching Pi-hole
  • blocked domains are appearing
  • nothing critical is being broken

14.8 Allowlist only what is necessary#

If a site or app breaks:

  1. open Query Log
  2. find the blocked domain
  3. allowlist only the required domain
  4. retest

Avoid broad wildcards unless absolutely necessary.

15. Verify clients are using Pi-hole#

On a client machine, inspect the DNS server it received from DHCP.

Windows#

ipconfig /all

Linux with systemd-resolved#

resolvectl status

macOS#

scutil --dns

Verify the active DNS server is your Pi-hole IP.

Example expected result:

DNS Server: 192.168.1.10

Then browse to the Pi-hole dashboard and confirm queries appear in real time.

16. Update and maintain Pi-hole#

Update Pi-hole itself#

Enter the container:

pct enter <CTID>

Then run:

pihole -up

Update the container OS packages#

Inside the container:

apt update && apt full-upgrade -y

Restart the container if needed#

From the Proxmox host:

pct restart <CTID>

17. Troubleshooting#

Pi-hole web UI does not load#

Check container status:

pct status <CTID>

Check the assigned IP:

pct config <CTID>

Check connectivity from another host:

ping 192.168.1.10

DNS queries fail#

Test directly against Pi-hole:

nslookup google.com 192.168.1.10

If that fails, enter the container and test outbound connectivity:

pct enter <CTID>
ping 1.1.1.1
ping google.com

If IP ping works but DNS name resolution inside the container fails, review upstream DNS settings.

Clients are bypassing Pi-hole#

Check client DNS configuration. If a client also has public resolvers configured, it may use them instead of Pi-hole.

Remove public secondary resolvers from DHCP unless they are a second Pi-hole.

Local hostnames do not resolve#

Review:

  • Local DNS records
  • Conditional forwarding settings
  • router DHCP hostname support

Two DHCP servers are active#

Symptoms include:

  • random IP assignments
  • incorrect DNS settings on clients
  • intermittent connectivity

Disable DHCP on either the router or Pi-hole so only one remains active.

For most home labs, this is the preferred order of design quality.

Preferred#

ISP modem in bridge mode
-> your firewall/router provides DHCP
-> DHCP advertises Pi-hole as DNS
-> Pi-hole uses Unbound or a chosen upstream resolver

Good#

Router/firewall provides DHCP
-> router DHCP advertises Pi-hole as DNS

Acceptable fallback#

ISP modem/router DHCP disabled
-> Pi-hole provides DHCP and DNS

19. Command reference#

Install Pi-hole via Community Script#

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/pihole.sh)"

List containers#

pct list

View a container config#

pct config <CTID>

Enter the Pi-hole container#

pct enter <CTID>

Set the Pi-hole web password#

pihole setpassword

Update gravity#

pihole -g

Update Pi-hole#

pihole -up

Restart the container#

pct restart <CTID>

20. Summary#

This setup gives you a clean Pi-hole deployment on Proxmox using the Community Script, plus a practical path for integrating it into your LAN.

The most important parts are:

  • keep Pi-hole on a static IP
  • verify DNS works before changing DHCP
  • configure DHCP to advertise Pi-hole
  • use Pi-hole DHCP only when the router cannot be configured
  • avoid public secondary DNS servers if you want reliable filtering
  • validate clients from both the operating system and the Pi-hole query log