Pi-hole V6 for Home Assistant: a custom integration that outgrew its original job

Why it exists, and what changed in 2025

This custom integration restored compatibility between Home Assistant and Pi-hole, which was no longer supported by the native integration. Today, this integration offers additional and complementary features.

The reason is stated plainly in the Description section. Due to major changes in the Pi-hole API, the native integration with Home Assistant was no longer functional for several months in 2025, until August 2025. The Pi-hole V6 Integration added compatibility with the new API in Home Assistant, aimed to restore compatibility and provide Pi-hole management directly from Home Assistant.

That is a useful case study in how the Home Assistant ecosystem absorbs a breaking change in a dependency. The native integration lives in Home Assistant core, so a change in Pi-hole's API could not be fixed until a Home Assistant release shipped the fix, which left users of Pi-hole V6 without the integration for months. A custom integration in the user's own Home Assistant install could be updated independently, and that is exactly what this one did.

The original component, the native Pi-hole integration, allows you to retrieve statistics and interact with a Pi-hole system.

The important caveat in the README is a note that says the integration remains active and does not only restore full functionality but also offers additional and complementary features to the native integration. The word today is doing real work there. The project started as a compatibility patch and has become a superset, and the FAQ at the end of the document explicitly lists the advantages of using this integration compared to the core one.

The project is MIT licensed, the primary language is Python, the default branch is develop, and the last push was on 2026-10-18. The recent releases are three betas of the same version, v1.22.0b3, v1.22.0b2 and v1.22.0b1, published on consecutive days in October 2026, which tells you the project ships betas often and that the stable line moves behind them.

The maintainer is Bastien Gautier, and the badges confirm the packaging: a HACS validation workflow and a HASSFEST validation workflow, both of which are the checks Home Assistant requires before an integration is considered fit to install.

Installing it through HACS, and the manual route

The installation section gives two routes, and the first is the one most people will use.

Through HACS, you add this repository as a custom repository to HACS, use HACS to install the integration, restart Home Assistant, and set up the integration using the UI. The custom repository link carries the owner, the repository and the category, and the setup link points at the config flow for the domain pi_hole_v6.

HACS is the Home Assistant community store, and requiring people to add a custom repository is the standard way a non-core integration is distributed. The alternative is that the integration is in Home Assistant core, which is what happened to the native Pi-hole integration and which is a much bigger commitment for a maintainer to take on.

The manual route is four steps: download the integration files from the GitHub repository, place the integration folder in the custom_components directory of Home Assistant, restart Home Assistant, and set up the integration using the UI.

Both routes end the same way, and that is the point. Once the files are in custom_components/pi_hole_v6, Home Assistant discovers the integration the same way it discovers a core one, and the setup goes through a config flow, which is the UI wizard that collects the connection details and creates the entry. The difference between the two routes is only how the files arrive.

The domain name matters more than it looks. It is pi_hole_v6 rather than pi_hole, so the custom integration does not collide with the native one. That means you can have both installed at once, which is presumably how the author intends you to compare them, and the README's framing of the advantages over the core integration only makes sense if both are present.

The repository layout is conventional for a HACS integration. There is a custom_components/ directory holding the integration itself, a docs/ directory, a hacs.json describing the integration for the store, a templates/ directory, a scripts/ directory, an img/ directory for the screenshots, and a .devcontainer/ for development. The tooling is a .pre-commit-config.yaml, a .commitlintrc.mjs, a pyrightconfig.json, a ruff configuration inside the pyproject.toml and a requirements.txt.

What the integration actually exposes

The feature list is short, and it is the short list of a project that started as a fix:

Monitor Pi-hole status. Enable and disable Pi-hole via Home Assistant. Retrieve filtering statistics. And compatibility with the Pi-hole V6 API.

The switches are the part that goes beyond the native integration, because enabling and disabling the DNS blocker from Home Assistant is a real control rather than a reading. It also means the entity sits in a control domain rather than only a sensor domain, which is why the recorder exclusion advice later in the README matters.

The sensors are enumerated in a diagram in the README, and a complete list with explanations is available in the documentation at docs/guide-explained-entities.md. The FAQ gives the shape of the set by naming what is updated on which schedule: the blocking status, the switches, the network device trackers and the client counters are updated every two minutes, and the cumulative statistics, meaning blocked and total queries, unique domains, FTL messages and version checks, every five minutes. Both frequencies are configurable, and the configuration page is docs/guide-configuring-refresh.md.

The two-minute and five-minute split is a sensible design and worth understanding, because it explains the whole data model. The fast group is state: is it blocked right now, is the switch on, which clients are connected. The slow group is counters: totals that only ever increase. So the fast group produces rows in the Home Assistant database every two minutes per entity, and the slow group produces a row every five minutes. That is the number that decides whether your database grows to something you have to prune.

The documentation set in the repo/guides directory shows the depth of the project beyond the core integration. There is a guide for adding a new service for people who hit problems, a guide for implementing Pi-hole controls in a dashboard, a guide for optimising the Home Assistant database, a guide for network device tracking including filtering and manual removal, and a guide with additional configuration information aimed at people who need more explanation to install or configure it.

The Pi-hole Card, and the translation effort behind the project

There is a companion frontend project that the README points at, and it is not part of this repository.

After installing the integration you can enhance your Home Assistant setup with the Pi-hole Card, a Lovelace card offering a dashboard designed for managing and monitoring your Pi-hole DNS ad blocker, with real-time statistics and controls in an interface that aligns with Pi-hole's design aesthetics. It is developed by warmfire540, and the installation instructions are in the homeassistant-extras/pi-hole-card repository.

Splitting the card out is the right call for the maintainers, because a Lovelace card is a frontend artefact with a different release cycle and a different dependency set from a Python integration, and coupling them would mean every card change needed a Home Assistant integration release. The cost is that there are two things to install and two things to keep an eye on.

The translation section is the other thing that shows the project's real shape. The integration is currently translated in fifteen languages, and every one except English names the contributor: Czech thanks kukulich, Dutch thanks jverlaan, French, German thanks Christian, Greek thanks ChriZathens, Norwegian thanks emigrating, Polish thanks jacksonafide, Portuguese from Brazil thanks tangobones, Russian thanks ProFiLeR4100, Slovak thanks milandzuris, Spanish thanks dmbuil, Swedish thanks aleexolsson, Turkish thanks habil, and Ukrainian thanks ProFiLeR4100 as well.

That list is a good description of what a Home Assistant custom integration actually is. The maintenance burden is not the code, it is the long tail of people in different countries who need the interface in their own language, and the fact that two languages have the same contributor shows a translator covering both Russian and Ukrainian.

There is also a home-assistant branded logo image hosted on the Home Assistant brands service, which is the mechanism for a custom integration to display a proper icon in the UI rather than a generic placeholder, and it is worth knowing that exists if you ever build one of these.

Debugging, and the logging advice that comes with a warning

The debugging section is short and includes a piece of advice that is easy to skim past.

To show the info and debug logs for the integration you enable logging in configuration.yaml:

logger:
  default: warning
  logs:
    # Log for Pi-hole V6 integation
    custom_components.pi_hole_v6: debug

The default is warning with the integration itself raised to debug, which is the standard Home Assistant logging configuration. The integration domain appears under the custom_components prefix, which is the convention for a custom integration and is different from how a core integration is named in the same file.

Then the warning, and it is the sentence worth remembering: logs do not remove sensitive information so careful what you share, check what you are about to share and blank identifying information.

That is a real caution rather than boilerplate, and the reason is specific to this integration. A debug log of a Pi-hole integration contains the names of the devices on your network and the domains they have queried, which is the sort of thing people paste into an issue tracker without thinking about it. The README's advice to blank identifying information before sharing is the mitigation.

The rest of the documentation set continues the same practical bent. There is a page explaining how to optimise the Home Assistant database, which given the two-minute polling is likely the most immediately useful page in the repository for a long-running install, and a page on network device tracking covering filtering and manual removal of entries.

The dependency picture in the pyproject.toml is also worth a glance for anyone tracking Home Assistant versions. The project pins homeassistant to 2026.2.1 and Python to a range of at least 3.14.2 and below 3.15, and the classifiers list Programming Language :: Python :: 3.14 with a development status of 5, Production/Stable. The requirements.txt in the repository pins a different homeassistant version, 2026.7.0, along with the linting tools, so the development environment runs a newer Home Assistant than the minimum the library declares. That is normal practice for a project that supports a range of core versions, and it also tells you the project is tracking recent Home Assistant releases closely.

Editorial conclusion

Adopt this integration if you run Pi-hole V6 and want more control from Home Assistant than the native integration gives, particularly the switches, the client counters and the Pi-hole Card. Do not expect it to be the same thing as the native integration, because it is a third party project maintained by one person with a distinct domain of pi_hole_v6, and it is still on a 1.x beta line. Before you install, read the refresh frequency page, because the default polling of two minutes for status and five minutes for cumulative statistics is the main thing that affects how you size your database, and consider excluding the high-churn sensors from the Recorder as the optimisation guide suggests.

Frequently asked questions

Official sources

1. bastgau/ha-pi-hole-v6 on GitHub
2. Issues
3. License: MIT
4. README
5. Releases