Home Assistant Community Add-on: Pi-hole

This add-on is provided by the Home Assistant Community Add-ons project.

GitHub Release GitLab CI Project Stage Project Maintenance

Supports armhf Architecture Supports armv7 Architecture Supports aarch64 Architecture Supports amd64 Architecture Supports i386 Architecture

Deprecation warning

This add-on is in a deprecated state!

The Pi-hole add-on is now deprecated and will no longer be supported, maintained and will not receive future updates or fixes.

Pi-hole used to be a great solution to filter network traffic, but it has been a challenge to keep/get it in a working state as an add-on.

Meanwhile, the AdGuard team published an alternative: AdGuard Home.

AdGuard Home as surpassed Pi-hole in terms of capabilities, features, and stability, and Home Assistant provides a good integration with AdGuard. Above all, the AdGuard Home team has been supportive in developing the add-on.

For those reasons, it is no longer viable to keep maintaining the Pi-hole add-on, which has been problematic at best.

We strongly recommend migrating to the AdGuard Home add-on, which is available in the add-on store.


Pi-hole is an advertising-aware DNS- and web server, meant to be run on a dedicated Raspberry Pi connected to your home network. Pi-hole lets you block advertisements for every device that connects to your network without the need for any client-side software.

This add-on is a port of Pi-hole to be able to run on Home Assistant and is based on Alpine Linux and is using Docker.

Repository on GitHub

Looking for more add-ons?

The primary goal of our add-ons project is to provide you (as a Home Assistant user) with additional, high quality, add-ons that allow you to take your automated home to the next level.

Check out some of our other add-ons in our Home Assistant Community Add-ons project.


About the author of this add-on

Hi there!

I am Franck Nijhof, and I have 30 years of programming experience, in many languages. I am using this experience to work on the Home Assistant project by giving back my knowledge and time to the open source community.

The add-on you are currently looking at right now was developed/packaged by me. It is not the only add-on I have created; there are many many more :wink:

However, I have a problem… I am an addict. A :coffee: addict that is. Lucky for you, I turn that C8H10N4O2 (caffeine molecule) into code (and add-ons)!

If you want to show your appreciation, consider buying me a cup of high octane wakey juice by clicking on the “By me a coffee” image below! :heart:

Buy me a coffee

Or, become a Patron and support my work!

Enjoy your add-on, while I enjoy the brain juice. :coffee:

Thanks for all the :two_hearts:


Join our Discord server Follow me on Twitter Flollow me on Instragram Follow me on GitHub Follow me on YouTube Follow me on Twitch patreon-icon

P.S.: In case you want to ask me a question: AMA (Ask Me Anything). Most of the time I am online at the Discord chat. (I go by @Frenck in there as well).

:tada: Add-on: Pi-hole v0.1.0

Time for a new add-on and this is not a small one. It is arguably the most requested Hass.io add-on! :exploding_head:

In the poll of this topic alone, it got 45% of the votes, which are more than 200 people who voted for this add-on! :white_check_mark:

Pi-hole is an advertising-aware DNS- and web server, meant to be run on a dedicated Raspberry Pi connected to your home network. Pi-hole lets you block advertisements for every device that connects to your network without the need for any client-side software.

This add-on is a port of Pi-hole to be able to run on Hass.io and is based on Alpine Linux and is using Docker.


  • Initial release :tada:

Since this is the first release of this add-on, I’m looking forward to your feedback!

WARNING: This add-on is a complex one and since this is the first release, there are undoubtedly bugs. Please report them on GitHub and I will get them fixed. :bug:

Thanks to everybody who requested or voted for this add-on. :+1:

So, what is going to be the next add-on? :wink:


Wow thanks! Say… when I try to add https://github.com/hassio-addons/addon-pi-hole to my hass.io list it just disappears… I tried the parent folder too which just gave me an “unknown” category, what am I doing wrong here? I have added others in the past, this one just doesn’t work for me.

Nvm, just took restarting hass.io. Must’ve been a bug.

Please read the documentation instead of “just doing”. Add the following repository:

Thx a lot, works great.

One question.
Is there a way to add Whitelist Domains via the commandline?
Like this: pihole -w themoviedb.com

And one little issue.

The “Open Web UI” Button opens this site https://xxx.xxx.xxx.xxx:80/ instead of https://xxx.xxx.xxx.xxx:80/admin/index.php

and https://xxx.xxx.xxx.xxx:80/ shows as blocked?!?!?


No that is not possible due to the design of Hass.io. The whitelist option is available in the admin web interface.

Ow shit z-wave… Sorry :blush: Will fix this in the next release.

Hmm, this is probably because the Pi-hole script does not expect the port number to be there…
I will look into a possibility to patch this.

Thank you for reporting these!



I can’t seem to start the pi-hole addon. I am getting this in the logs when trying to start pi-hole:

[s6-init] making user provided files available at /var/run/s6/etc...exited 0.
[s6-init] ensuring user provided files have correct perms...exited 0.
[fix-attrs.d] applying ownership & permissions fixes...
[fix-attrs.d] 01-resolver-resolv: applying... 
[fix-attrs.d] 01-resolver-resolv: exited 0.
[fix-attrs.d] 01-sudo: applying... 
[fix-attrs.d] 01-sudo: exited 0.
[fix-attrs.d] 02-nginx: applying... 
[fix-attrs.d] 02-nginx: exited 0.
[fix-attrs.d] 03-pihole: applying... 
[fix-attrs.d] 03-pihole: exited 0.
[fix-attrs.d] done.
[cont-init.d] executing container initialization scripts...
[cont-init.d] 00-banner.sh: executing... 
 Hass.io Add-on: Pi-hole v0.1.0
 Network-wide ad blocking using your Hass.io instance
 From: Community Hass.io Add-ons
 By: Franck Nijhof <[email protected]>
[cont-init.d] 00-banner.sh: exited 0.
[cont-init.d] 01-log-level.sh: executing... 
Log level is set to INFO
[cont-init.d] 01-log-level.sh: exited 0.
[cont-init.d] 02-updates.sh: executing... 
INFO: You are running the latest version of this add-on
[cont-init.d] 02-updates.sh: exited 0.
[cont-init.d] 10-patches.sh: executing... 
[cont-init.d] 10-patches.sh: exited 0.
[cont-init.d] 11-pihole.sh: executing... 
[cont-init.d] 11-pihole.sh: exited 1.
[cont-finish.d] executing container finish scripts...
[cont-finish.d] done.
[s6-finish] syncing disks.
[s6-finish] sending all processes the TERM signal.

Also, when attempting to open the web GUI; I am getting an error. It’s probably related to having DuckDNS as an addon as well. What port/IP is it trying to open?

Thanks, and looking forward to using this fully in the future! looks great.

@derrick1985 I’m sorry this is a known issue (a bug) that will be solved in the next release (it is already solved, but not released yet).

This issue is caused by a failure in the IPv6 detection in case the network does not offer IPv6. Please disable IPv6 in the add-on options and start it again.

Thanks; that solved it.

1 Like

:tada: Add-on: Pi-hole v0.1.1

Full Changelog


  • Incorrect URL in “Open Web UI” button #1
  • Addon fails to start when IPv6 is not present on network #3
  • Visiting blocked page with port number does not redirect to admin #2

This update is now available in your Hass.io panel.


Thanks for the Pi-hole add-on!!!
Can you give me an example of the options, if I want to use the pi-hole add-on additional to the duckdns add-on?

Is that right:

"log_level": "info",
"password": "pass",
"update_lists_on_start": false,
"web_port": 80,
"dns_port": 53,
"ssl": true,
"certfile": "fullchain.pem",
"keyfile": "privkey.pem",
"interface": "",
"ipv6": false,
"ipv4_address": "",
"ipv6_address": "",
"virtual_host": "https://xxx.duckdns.org"

In my router I forward 443 to 8123.

If I click the Open Web UI button- the browser tries to load https://xxx.duckdns.org:80/admin/index.php

But I only get: the site could not load because the server can only get a not safe connection

“Diese Website kann keine sichere Verbindung bereitstellen

xxx.duckdns.org hat eine ungültige Antwort gesendet.

If I try it with https:, the Web UI opened
I am using v0.1.1

Thank you for your message. Unfortunately, this is not something that is fixable and is occurring in this specific setup. Hass.io assumes everything is on the same base URL as the URL you are currently visiting Home Assistant on. Add-on developers cannot influence this.

In your case, you are clicking the “Open Web UI” button while already on xxx.duckdns.org. Hass.io will use that domain for the button as well.

Besides the “Open Web UI” button, everything will function normally.

You probably will experience this with other add-ons as well.

Ah ok! Thanks for the information!

Another question:
I try to use the Pi-hole sensor with the pi-hole add-on.
My Config:

 - platform: pi_hole
   ssl: true

But all sensor values are “unavailable”

@Marius82 I’m not sure. I will test this and get back to you.

1 Like

Have you got verify SSL to false ? mine wouldn’t work until I did that. for host I put localIP:portofwebadmin and verify_ssl: false

I have duckdns / letsencrypt setup using port 80, and pi-hole on port 8081, is that why I dont get the pretty BLOCKED page and instead just get a 404 ? D:

I can’t add the repository to my Hass.IO installation. I’m attempting to add the “https://github.com/hassio-addons/repository” repository as shown below, but when I click save the newly added line disappears and no new repositories are actually added.

It worked for me. I just had to scroll down to see. A new section for “Community Hass.io Add-ons” is added.

I just tried it from my phone and it worked on the first try. I guess it might be a Chrome Desktop issue I was having on the computer last night.

1 Like