Pi-hole
pi-hole · Privacy
GitHub stars
61,560Awaiting first sync
No measured star history yet
What is Pi-hole?
Pi-hole stops ads and tracking at the network level, so you set it up once instead of on every phone, laptop and TV. It works by answering DNS lookups and refusing the ones that point to ad and tracking domains. You keep the logs and settings on your own hardware, which makes it easy to see what your devices connect to.
Pi-hole is a DNS sinkhole that blocks ads and trackers for every device on a network without installing software on each one. It runs on a small Linux machine such as a Raspberry Pi, caches DNS answers, and can act as the network's DHCP server. A web interface, a command-line tool and a REST API show statistics and manage blocklists, allowlists and settings.
Core capabilities
- Blocks ads in apps, smart TVs and other devices that cannot run a browser extension.
- Shows every DNS query, which device asked and what Pi-hole did with it.
- Groups let different devices follow different blocklists and domain rules.
Blocking at the DNS level
Pi-hole acts as the DNS server for your network and refuses lookups for domains on its blocklists. Because blocking happens before any content downloads, it also covers places a browser extension cannot reach, such as mobile apps, smart TVs and IoT devices. You can subscribe to community blocklists and allowlists that update automatically, and add your own allowed, denied or regex rules. Pi-hole caches DNS answers, so repeat lookups are faster, and it blocks over both IPv4 and IPv6.
- DNS
- Ad blocking
- Blocklists
- Regex
Dashboard, command line and API
The built-in web interface shows total and blocked queries, activity per client, upstream servers and the most requested and most blocked domains. A query log stored in a long-term database lets you search any time range, and four privacy modes control how much query detail is kept. The pihole command covers the same tasks from a terminal, including allow and deny rules, updating lists, debugging and enabling or disabling blocking. A REST API with built-in documentation and app passwords lets scripts and home automation tools connect, and Teleporter backs up and restores the whole configuration in one file.
- Web interface
- Query log
- CLI
- REST API
- Privacy modes
Run it yourself under EUPL-1.2
Install with the one-step script at install.pi-hole.net, download and read basic-install.sh first, or use the official pihole/pihole Docker image. Officially supported systems include Debian, Ubuntu, Raspberry Pi OS, Fedora, CentOS Stream, Alpine and Armbian, and the documented minimum is 512MB of RAM and 2GB of free space. Pi-hole needs a static IP address and port 53 free for DNS. Pi-hole is released under the EUPL-1.2 licence.
- Self-hosted
- Raspberry Pi
- Docker
- EUPL-1.2
Where it fits
Use cases
- 01
Block ads on every device in the office or home
Install Pi-hole on a Linux machine with a static IP address, using the automated installer or the pihole/pihole Docker image. Then set your router's DHCP settings to hand out Pi-hole as the DNS server, so every device uses it without any further setup. If the router cannot change its DNS server, turn on Pi-hole's built-in DHCP server instead.
- 02
Apply different filtering to different devices
In Group Management, put clients into groups and give each group its own subscribed lists and domains. For example, a group for children's tablets can use stricter blocklists while work laptops use a lighter set. Devices not placed in a group fall into the Default group.
- 03
Find out what devices on the network are contacting
Open the Query Log in the web interface to see each domain that was looked up, which device asked and whether it was blocked. Long-term statistics let you filter any time range, and a domain can be allowed or denied in one click. The same data is available from the command line with pihole tail and pihole query, or through the REST API.