Home Assistant Community Add-on: AdGuard Home

Tags: #<Tag:0x00007f7806cd8a40> #<Tag:0x00007f7806cd8950>

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

Network-wide ads & trackers blocking DNS server.


AdGuard Home is a network-wide ad-and-tracker blocking DNS server with parental control (adult content blocking) capabilities. Its purpose is to let you control your entire network and all your devices, and it does not require a client-side program.

AdGuard Home provides a beautiful, easy and feature-rich web interface to easily manage the filtering process and its settings.


The installation of this add-on is pretty straightforward and not different in comparison to installing any other add-on.

  1. Ensure your Home Assistant device has a static IP and static external DNS servers!
  2. Search for the “AdGuard Home” add-on in the add-on store and install it.
  3. Start the “AdGuard Home” add-on.
  4. Check the logs of the “AdGuard Home” to see if everything went well.
  5. Click the “OPEN WEB UI” button and log in with your Home Assistant account.
  6. Ready to go!


You can always get support here at the Home Assistant community forums, join the conversation!

You have several options to get them answered:

You could also open an issue on GitHub, in case you ran into a bug, or maybe you have an idea on improving the addon:

We will do our best to help you out!

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 supporting me for buying a cup of high octane wakey juice via one of the platforms below! :heart:

Sponsor Frenck via GitHub Sponsors

Support Frenck on Patreon

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).


Tweet release notification:

1 Like

Thanks for the addon. Has anyone experiences compared to pi-hole?

Pi-hole has more capabilities, but if you are looking for a simple, quick ad-blocker then this is a nice and lightweight option. I’ve also picked up some rumors about a Home Assistant integration… (with automation capabilities) :speak_no_evil:

AdGuard Home is more lightweight, takes up fewer resources and additionally provides adult content filtering. It also supports DOH (DNS over HTTP) and DNS with TLS.


FYI, your link for “Open an issue for the addon: AdGuard Home” goes to the addon-spotify-connect issue page, not the AdGuard one.

Thanks! Corrected!

1 Like

Getting the below error message. Changing the DNS port removes the error but the web ui does not load.

2019/01/10 20:03:36 Couldn't start forwarding DNS server, cause: couldn't listen to UDP socket, cause: listen udp :53: bind: address already in use

I’m having the same issue as @Maaniac it seems.

Upon starting the addon I get the normal start-up messages, then this:

2019/01/10 21:56:10 Creating the UDP server socket
2019/01/10 21:56:10 Couldn't start forwarding DNS server, cause: couldn't listen to UDP socket, cause: listen udp :53: bind: address already in use

Then it appears to try again, generating the same error repeatedly.

If I change the DNS port from 53 to something else, the addon starts and I can access the WebUI just fine.

Since the launch of AdGuard Home I planned to try this. Also trying to find a suitable docker image etc.
And here we go, perfectly integrated into Hass.io.

Setup took no longer than 5 minutes, and the first ads are already blocked. The DNS with TLS is a great and appreciated plus.
Well done @frenck, thanks!

I am having trouble with this add-on.
I got it to load and have access to the web interface, but it isn’t blocking any ads.
I’m sorry I am not technical, and presume that is my problem.
I have set a static IP on my raspberry pi.
The static external DNS server issue is where I am uncertain.
I have Google WiFi. My DNS is set for automatic (
Should I change this setting to the ISP’s DNS? If that is my likely issue, other than making this add-on work, what potential risks come with this setting as opposed to the automatic setting?
I appreciate your patience and help!

After you have the addon running, it would be best to check the wiki for AdGuard Home itself for more information on how to use it:

In short, you change your router’s DNS to the box running this addon, then in the addon set the upstream DNS to google or cloudflare, or whatever you would like.

1 Like

I’m not sure if you are having this problem for the same reason I am, but I think I found the solution for mine.

I’m running HassIO on an Ubuntu box. Ubuntu uses systemd-resolved which starts at boot and binds to port 53.

The “solution” was to disable it, by running Sudo systemctl disable system-resolved in the Ubuntu host, then editing /etc/resolv.conf so only my router was listed as a nameserver. Then reboot the host.

I’m not sure if this is the 100% correct way to fix the issue, but it seemed to work.


I use a raspberry pie.
Is it wrongly understood that on my router should set the DNS as my raspberry pie ip port 53? or is it only the ip?

Just the IP should be fine. The default DNS port is 53, so if you’re using that, the IP should be all that needs to be given.

1 Like

Thanks very much for this info… I had to use a slightly different command but same result… it all seems to be working correctly now. :tada:

sudo systemctl disable systemd-resolved.service
sudo reboot now

Hi guys,

I’m not 100% about the setup. My pi has an static IP address, but I’m not sure, what " static external DNS servers!" means.

Can somebody please explain what that means? Do I need to set anything here?

1 Like

surely thats the DNS server(s) that you want Adguard to use for its DNS queries… ie: or or the default DNS server of your ISP. You would point your devices to Adguard (your RPi IP) but Adguard needs to resolve DNS queriers too so it needs an EXTERNAL IP to do so, such as those I gave above

1 Like

Thanks! But where do I need to set this? Inside the AdGuard panel?

Currently I can’t access the panel. It asks me for my username and when I use my HA login, it tells me that this is wrong. Is this maybe caused by the activated 2fa?

Here is the issue from the log:

2019/01/18 13:29:42 [warn] 586#586: *9 [lua] ha-auth.lua:65: authenticate(): Authentication against Home Assistant failed!, client: 192.168.yyy.xx, server: _, request: "GET / HTTP/1.1", host: "192.168.yyy.xx:3210"


No, inside the adguard-home addon, under settings, is where you set your Upstream DNS servers.

The setting a static external DNS server for the PI is something separate, and not 100% necessary it seems, since I never bothered doing it and everything still works fine.

1 Like