What is Pi-hole: Block ads across your network with an open source DNS sinkhole

Pi-hole is an open source DNS sinkhole that protects all the devices on your network from advertising, trackers and unwanted domains without installing anything on each mobile phone, tablet or smart TV. The project, hosted at github.com/pi-hole/pi-hole, accumulates more than 59,000 stars on GitHub and is presented as «a black hole for Internet advertisements»: a black hole for internet advertisements at the network level.

How it works (and why it's not a browser extension)

When a device requests to resolve a domain—for example ads.example.com—the DNS query first goes through the Pi-hole. If the domain is on a block list, Pi-hole responds with a null or local address and the request never goes out to the ad server. The result:

• Blocking in native apps: mobile games, smart TVs and players with integrated advertising, where there is no browser extension.
• Less traffic and perceived latency: Pi-hole caches frequent DNS queries and speeds up everyday browsing.
• Privacy: you reduce the tracking surface by cutting off telemetry and analytics domains at the network level.
• IPv4 and IPv6: modern blocking on both protocols.

Unlike uBlock Origin or AdGuard in the browser, Pi-hole acts as a DNS server for the network. A single point of control protects laptops, consoles, smart speakers and visitors connected to your Wi-Fi.

Requirements and hardware

Pi-hole is lightweight: it runs on Raspberry Pi, a Linux mini PC, a VM or a cloud server. The official repository highlights that, with server hardware, it can handle hundreds of millions of queries. For a typical home, a Raspberry Pi 4 or a Docker container on a NAS is enough.

Main components of the stack:

• FTLDNS — proprietary daemon that powers statistics, the web dashboard and the API with low latency.
• dnsmasq — DNS/DHCP base on which Pi-hole builds filtering.
• Blocklists — updateable with the pihole updateGravity command (script gravity.sh from the repo).

Installation: four official methods

The repository's README documents these paths, from fastest to most auditable:

Method 1 — Automatic installer (one command)

curl -sSL https://install.pi-hole.net | bash

The interactive wizard guides setup in less than ten minutes. It is the recommended path for most home users.

Method 2 — Clone the repository

git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole 
cd "Pi-hole/automated install/" 
sudo bash basic-install.sh

Allows you to review the installer code before running it — useful if you prefer not to use curl | bash.

Method 3 — Download the script manually

wget -O basic-install.sh https://install.pi-hole.net 
sudo bash basic-install.sh

Method 4 — Docker

For containerized environments, the team maintains official images in the pi-hole/docker-pi-hole repository. Ideal if you already manage services in Docker Compose or home Kubernetes.

Post-installation: make the entire network use Pi-hole

After installing, the critical step is for the devices to resolve DNS through Pi-hole:

1. Router (recommended): in the router's DHCP settings, indicate the IP of your Pi-hole as the primary DNS server. All clients that obtain IP automatically will be protected.
2. Pi-hole DHCP: If the router does not allow changing DNS, activate the Pi-hole integrated DHCP server (disable the router's DHCP first to avoid conflicts).
3. Manual per device: As a last resort, configure the Pi-hole IP as DNS on each computer.

Once operational, the panel is usually at http://pi.hole/admin/ (if you use Pi-hole as DNS) or at http://<IP_DE_TU_PI-HOLE>/admin/.

Web panel and command line

Pi-hole offers two complementary interfaces:

Web dashboard

• Responsive and mobile-friendly interface.
• Password protection.
• Query graphs, percentage of blocks and top domains/clients.
• Filterable and sortable query log.
• Long-term statistics and allow/deny list management.

CLI pihole

All essentials can be managed without opening the browser:

• Allowlist / Denylist (formerly whitelist/blacklist) and regex expressions.
• Debugging utility (pihole -d).
• Live log, list update and query of blocked domains.
• Turn filtering on and off temporarily.

FTLDNS API for integrations

FTLDNS exposes a REST API documented at pi.hole/api/docs. README examples:

curl --connect-timeout 2 -ks "https://pi.hole/api/stats/summary" \ 
-H "Accept: application/json" 

pihole api config/webserver/port 
pihole api stats/summary

Available metrics: blocked domains, queries of the day, percentage of filtered ads, unique customers, queries cached and forwarded to the upstream DNS of your choice (Cloudflare, Quad9, Google, etc.).

Pi-hole vs. other solutions

Pi-hole does not replace a firewall or an antivirus, but it complements home privacy well:

• vs. browser extensions: Pi-hole covers the entire network and apps outside the browser; extensions are still useful for fine filtering on specific pages.
• vs. AdGuard Home / NextDNS: Pi-hole is the historical open source benchmark with the largest community; Alternatives offer different interfaces or DNS in the cloud without their own hardware.
• vs. Cloud DNS: Pi-hole keeps data on your LAN; you control lists, logs and upstream.

Limitations that should be known

• Ads on the same domain: if the ad is served from the same host as the content (CNAME cloaking or first-party ads), DNS blocking is not always enough.
• HTTPS: Pi-hole does not inspect encrypted traffic; blocks by domain name, not URL or page content.
• False positives: legitimate domains in aggressive lists can break services; the allowlist corrects this.
• Maintenance: it is advisable to update lists and the Pi-hole itself; The recent stable version is v6.4.2 (April 2026).

Community and support

The team recommends the Discourse forum as the main channel. Before opening a thread, consult the FAQs. The project accepts contributions on GitHub: bug reports, new features, and pull requests for scripts like basic-install.sh and gravity.sh.

In summary

What is Pi-hole? An open source DNS sinkhole that blocks ads and trackers throughout the network. How is it installed? With a script in Linux, cloning the repo or via Docker. What do you need next? Point the router's DNS (or DHCP) to your Pi-hole. Why use it? Protect smart TVs, mobile phones and apps without software on each device, with web panel, CLI and API. Where to start? Official repository on GitHub.