Home Assistant Community Add-on: UniFi Controller

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 aarch64 Architecture Supports amd64 Architecture Supports i386 Architecture

The UniFi Controller allows you to manage your UniFi network using a web browser.



This add-on runs Ubiquiti Networks’ UniFi Controller software, which allows you to manage your UniFi network via the web browser. The add-on provides a single-click installation and run solution for Home Assistant, allowing users to get their network up, running, and updated, easily.

This add-on supports all Home Assistant supported architectures, including the Raspberry Pi.


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

  1. Search for the “UniFi Controller” add-on in the add-on and install it.
  2. Start the “UniFi Controller” add-on.
  3. Check the logs of the “UniFi Controller” to see if everything went well.
  4. Click the “OPEN WEB UI” button, and follow the initial wizard.
  5. After completing the wizard, log in with the credentials just created.
  6. Go to the settings (gears icon in the bottom left) -> Controller (tab).
  7. Change the Controller Hostname/IP to match the IP or hostname of
    the device running Home Assistant.
  8. Check the box Override inform host with controller hostname/IP.
  9. Hit the “Apply Changes” button to activate the settings.
  10. Ready to go!


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

Questions? 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:

:information_source: At this moment our Home Assistant Community Add-ons Discord chat server and GitHub are our only official support channels. All others rely on community effort.

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

Thanks for this, looks great.

Is there an option to upgrade the controller version yourself?

1 Like

Updates will be provided by the project itself and will show up as a one click upgrade inside Hass.io.

1 Like

Silly question but it doesnt appear in the usual ‘Community hass.io addons’ list under add-on store. Do i need to do anything specific to refresh list?

It refreshes automatically every couple of hours. You can force a refresh by going into the add-on store and hitting the refresh button in the top right :wink:

Gah! Didnt see that button at all! Thanks :slight_smile:

1 Like

Installed and adopted the APs :slight_smile:

However, it won’t let me rename them like I used to do in the normal controller

EDIT: Looks like I needed to set LED Brightness. Didn’t have to in a local controller

The addon won’t start on Debian (Stretch) with Hassio. I have other addons running but it makes no difference if those are stopped.
I get a message on the console that there’s no ifupdown configuration found for the interface in the docker (veth387ab00).
Anything you can help here? Should I open an issue?


Please open an issue and be sure to post the debug logs as well. (P.s. I’ve tested this add-on on virtual machines and a Generic linux install as well…)

Found the issue - there was something running already on port 8080, changing this port to 8081 made the addon start. Thanks for your fast reply!

1 Like

Actually that is likely due to running the 5.8.22 stable candidate (i.e. beta but almost ready for release).

UBNT released 5.8.23 stable candidate today that fixes that bug and only shows the option now for the 1 model (BaseStationXG) that supports it.

I don’t see the 5.8.23 anywhere? The release logs are not showing them as well…?

That is because it is only available in the beta channel right now.

This is great, thanks. I assume it’s a fork of the normal Unifi controller and will be a few phases behind the normal releases?

It is not a fork. Add-ons are essentially Docker containers and therefore always a little behind (the update has to be released before it can be added to the container).

I followed the 11 step instruction, the add-on starts fine, but my AP is still stuck on Adopting - Disconnected - Adopting. I tried restarts of the AP and the add-on.

I have changed 8080/tcp to 8085 and 8443/tcp to 7443
The Unifi controller is available at https://mysite.duckdns.org:7443

9. Check the box Override inform host with controller hostname/IP.
I entered mysite.duckdns.org (without port). Correct?

Any suggestions?

Try entering the internal IP address of your Hass.io machine.
Secondly, at this point, I’m unsure if changing the ports may cause this.

1 Like

I just did what no man should - changed several things at the same time during troubleshooting.

  1. Changed 8443/tcp back to 8443
  2. Changed the Override inform host with controller hostname/IP to the internal IP (192.168.x.xx).
  3. Upgraded the AP from to (done from this add-on so the connection to the AP works fine)

However, still stuck on Adopting - Disconnected - Adopting.

And thanks for your prompt reply :slight_smile:

Since you’ve successfully updated the firmware, the basics are working. Nevertheless, the controller is sending out incorrect data to the AP in order for them to adopt. Two things to make sure:

  1. Ensure you have entered the correct IP address in the Controller Hostname/IP field.
  2. Ensure you have checked/enabled the option Override inform host with controller hostname/IP

(and of course, click the Apply Changes button.

This should be sufficient to get it working. Please note, it might take a few minutes for the controller/AP to pick up this change (e.g., they might be trying adopting now, with the old settings, already. This sequence has to fail, before it tries again with the new settings).