Cómo instalar Pi-hole
Bloquea anuncios y rastreadores en toda tu red instalando Pi-hole en tu servidor doméstico paso a paso.
Pi-hole blocks ads and trackers at the DNS level for every device on your network — phones, TVs, game consoles and laptops — with no client software. It works by answering DNS questions: when a device asks for the address of a known ad or tracking domain, Pi-hole refuses to answer, so the ad never loads. Here is how to run it with Docker, point your network at it and keep it healthy.
How DNS ad blocking works (and its limits)
Every time a device opens a website, it first asks a DNS server to translate the name into an IP address. Pi-hole is that server for your home. It checks each name against blocklists and returns nothing for the blocked ones.
This approach is fast and covers all devices, but it has limits:
- It cannot block ads served from the same domain as the content (some video platforms).
- It does not remove the empty space where an ad would have been.
- Devices that hard-code their own DNS server (some smart TVs) may bypass it.
For the best result, combine Pi-hole with a browser ad blocker on your computers.
Prerequisites
- A home server with Docker installed.
- A static address for the server. Set a DHCP reservation on your router, because if the server's IP changes, your whole network loses DNS. See the networking guide.
- Admin access to your router.
Step 1: Free port 53 on Ubuntu (if needed)
On Ubuntu, systemd-resolved often occupies the DNS port, and the container will fail to start with "address already in use". Check with:
sudo ss -lntup | grep ':53 'If systemd-resolved is listening, disable only its stub listener:
sudo mkdir -p /etc/systemd/resolved.conf.d
printf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/pihole.conf
sudo systemctl restart systemd-resolvedDebian servers without systemd-resolved can skip this step.
Step 2: Create the Compose file
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
ports:
- "53:53/tcp"
- "53:53/udp"
- "8090:80/tcp"
environment:
TZ: "Europe/Berlin"
FTLCONF_webserver_api_password: "change-me"
FTLCONF_dns_listeningMode: "all"
volumes:
- ./etc-pihole:/etc/pihole
restart: unless-stoppedNotes on the file:
- This uses Pi-hole v6 settings. Older v5 images used
WEBPASSWORDand a separateetc-dnsmasq.dvolume. If you are upgrading, check the release notes. - Replace
change-mewith a strong password. Keep secrets in an.envfile rather than in the Compose file; see Docker Compose best practices. - The web interface listens on port 8090 here, because port 80 is often already used by something else.
listeningMode: alllets Pi-hole answer requests that arrive through Docker's network translation.
Step 3: Start Pi-hole
docker compose up -d
docker compose logs -f piholeStep 4: Open the dashboard
Go to http://your-server-ip:8090/admin and log in with the password you set. The dashboard shows total queries, the percentage blocked, top blocked domains and which clients are the chattiest.
Step 5: Point your network at Pi-hole
The best option is to set Pi-hole as the DNS server in your router's DHCP settings, so every device uses it automatically. Alternatively, set it per-device for testing first. Some tips:
- Set a secondary DNS only if it is also Pi-hole. Adding a public resolver as a fallback means some queries bypass filtering.
- After the change, renew the lease on a device or reconnect it to Wi-Fi.
- If your router will not let you change DHCP DNS, you can run Pi-hole's own DHCP server instead, but only after disabling the router's DHCP.
Step 6: Verify it is working
Visit a known test page or just browse a few sites; many ads should vanish. On a computer, run nslookup doubleclick.net. It should return 0.0.0.0 or no address, when queried against Pi-hole. The dashboard's query log shows each request live.
Step 7: Choose good blocklists
The default list blocks a lot. Add reputable lists under Adlists if you want more, but don't overdo it: very large lists increase false positives and break sites. Start small, then add one list at a time.
- Use the allowlist to fix any site that misbehaves. The query log lets you whitelist a blocked domain with one click.
- Use groups to apply stricter filtering to certain devices, for example children's tablets.
- Avoid blocking telemetry domains that your smart home devices need to work.
Step 8: Make it reliable
DNS is critical: if Pi-hole stops, the internet appears to be "down" for the whole house. Protect against that:
- Keep Pi-hole on a reliable machine with a UPS.
- Back up the
etc-piholefolder so you can restore your settings (the Teleporter feature also exports them). - Consider running a second Pi-hole on a different device and listing both in your router.
- Monitor it with Uptime Kuma so you are alerted if DNS stops responding.
- Update regularly:
docker compose pull && docker compose up -d.
Bonus: local DNS names
Pi-hole can also resolve names for your own services. Under Settings → Local DNS Records, map media.home to your server's IP. Combined with a reverse proxy, you get friendly URLs inside your network.
Troubleshooting
- Container exits with a port error: step 1 — another service is using port 53.
- Websites don't load after the change: check that the server is reachable and the container is running. As an emergency fix, set your router's DNS back to a public resolver.
- Some devices still show ads: they use their own DNS (or DNS over HTTPS). Block outbound port 53 to other servers in your firewall, or use the router's DNS redirection.
- A site is broken: check the query log for a blocked domain and allowlist it.
Tips
- Consider AdGuard Home if you want encrypted DNS built in.
- Pair Pi-hole with a VPN so you get ad blocking when away from home. See WireGuard setup.
That is it — one small container now cleans up browsing for your whole home.
Artículos relacionados
How to Set Up WireGuard VPN
Self-host a WireGuard VPN to reach your homelab securely from anywhere: wg-easy in Docker, a manual wg-quick setup, split vs full tunnel, DNS, CGNAT and troubleshooting.
How to Install Nginx Proxy Manager
Install Nginx Proxy Manager with Docker, add proxy hosts and free Let's Encrypt certificates, use DNS challenges for internal names, add access lists and avoid common mistakes.
How to Set Up Caddy as a Reverse Proxy
Set up Caddy in Docker for automatic HTTPS in front of your homelab: Caddyfile examples, shared Docker networks, DNS-challenge certificates for internal names, auth, headers and troubleshooting.