This tutorial will show you how to install the Home Assistant software onto the Ubuntu operating system.
Home Assistant is a power piece of software that makes automating your home significantly more straightforward.
This software acts as the hub for all of the IoT devices around your home and allows you to perform actions depending on their status.
While the Home Assistant software doesn’t officially support Ubuntu, it is still possible to run the server since it is based on Debian. There may be a few things that don’t work exactly right but still should function. If you prefer to stick with a supported operating system, you should try moving to Debian 11.
You can get Home Assistant on Ubuntu in a couple of ways. The first is to use a virtual image and run it within a virtual container. The other is to install and run the “
Supervised” version of Home Assistant.
For this guide, we will focus on installing the Supervised variant of the software directly to the Ubuntu operating system. We will have a separate guide that covers installing Home Assistant through a virtual machine.
How to install Home Assistant Supervised to Ubuntu
In the following section, we will show you how to install the “
Supervised” version of Home Assistant to Ubuntu.
This process involves installing Docker, the OS-Agent, and Home Assistant.
Preparing Ubuntu to Run Home Assistant Supervised
1. Before we can install Home Assistant, we need to ensure that we have all the software we need to run it.
Our first step is updating the operating systems package list using the following command.
sudo apt update
2. Once the package list is up to date, you can install the packages Home Assistant Supervised requires to Ubuntu by running the command below.
sudo apt install apparmor jq wget curl udisks2 libglib2.0-bin network-manager dbus lsb-release systemd-journal-remote -y
3. The next thing we need to install to Ubuntu is Docker. Docker is used by Home Assistant to run various parts of its systems.
The easiest way to install Docker is to use the following command. This command uses curl to grab a script from the official Docker website and then executes it locally.
curl -fsSL get.docker.com | sh
4. The final thing you will want to do to prepare your system for Home Assistant is to ensure you have a static IP address.
We have guides covering how to set a static IP address on Ubuntu itself if you can’t access your router.
Installing the Home Assistant OS Agent
5. Our next step is to install the Home Assistant OS agent. This agent bridges the Ubuntu operating system and Home Assistant supervised.
To install this agent, we must first download it using the command below.
6. With the OS-Agent downloaded to your Ubuntu system, you can install it using the following command.
sudo dpkg -i os-agent_*
7. You can verify that the OS agent has been successfully installed by running the command below in the terminal.
gdbus introspect --system --dest io.hass.os --object-path /io/hass/os
If you have successfully installed the Home Assistant OS Agent to your Ubuntu system, you shouldn’t see any error messages from this command.
Installing Home Assistant Itself to Ubuntu
8. Finally, with everything in place, we can now install the supervised variant of Home Assistant to our Ubuntu system.
Our first step in this process is downloading the latest Home Assistant Supervised version.
9. With the Home Assistant Supervised package downloaded on your system, you can now install it.
Installing it is as straightforward as using the following command.
sudo BYPASS_OS_CHECK=true dpkg -i --ignore-depends=systemd-resolved ./homeassistant-supervised.deb
To get Home Assistant to install on Ubuntu, we have to disable several checks intentionally. First, we set the environment variable “
BYPASS_OS_CHECK” to “
true” so the installer won’t check we aren’t running Debian.
Secondly, we use the “
--ignore-depends” option to ignore the “
systemd-resolved” dependency. This dependency is installed under the name “
resolvectl” on newer versions of Ubuntu.
10. Once the installation finishes, you should see something like what we have shown below appear in your terminal.
The URL below is the one you will use to access your Home Assistant installation shortly.
[info] Within a few minutes you will be able to reach Home Assistant at: [info] http://homeassistant.local:8123 or using the IP address of your [info] machine: http://192.168.0.83:8123 [warn] A reboot is required to apply changes to grub.
11. Restart the Ubuntu operating system Before accessing your Home Assistant installation.
Restarting ensures all of the changes we have made will take effect. Failing to restart can lead to extra warnings within the Home Assistant web interface.
Accessing your Home Assistant Ubuntu Installation
Now that you have Home Assistant installed on the Ubuntu operating system, you will want to access its web interface.
1. By default Home Assistant is usually accessed through your Ubuntu device’s IP address on port
For example, our instance of this software is available to us by going to the following web address in a web browser.
Initial Setup Experience
2. Upon accessing your Home Assistant installation for the first time, you may get a message prompting you to wait.
This message lets you know the software is still finishing setting itself up on Ubuntu.
3. Once Home Assistant has set itself up, you will now get a chance to do some initial configuration.
Here you should fill out the details for your administrator account for Home Assistant (1.). With your details filled out you will need to click the “
CREATE ACCOUNT” button (2.).
Alternatively, if you have a backup, you can also restore from that by clicking the
"Alternatively you can restore from a previous backup” link (3.).
4. Next, you will be prompted to give this instance a name (1.).
Once you are happy with the name you have set, simply click the “
NEXT” button (2.).
5. Home Assistant uses various information about you and your location to provide a better experience.
The first bit of information it asks for is your address (1.). It uses this address internally to calculate information such as the weather. This data is never shared outside of your network.
Once you have filled out your address, click the “
NEXT” button (2.) to proceed.
6. Next, you can fill out some additional stuff about your location (1.). The more information, the more it helps your Ubuntu Home Assistant installation better for your needs.
Once you are happy, click the “
NEXT” button (2.).
7. You will now be prompted whether you want any data to be reported back to the Home Assistant developers. These bits of information are meant to be anonymized but are all disabled by default.
Turn these features on or off depending on your preferences (1.).
Once happy, click the “
NEXT” button to continue (2.).
8. Home Assistant will now list any devices automatically detected on your network. You can set them up now or later when you have more time.
Once you are happy, click the “
9. You now have Home Assistant running on your Ubuntu operating system.
For the most part, this should work with little to no issues. However, remember that the Home Assistant team does not officially support Ubuntu, so if things do go wrong there will be little to no support.
Hopefully, you should now have the Home Assistant software running on your Ubuntu device.
This software makes automating functionality within your home a much simpler process. This simplification is, in large, thanks to its very dedicated community.
Remember that this software is not officially supported on Ubuntu. We had to work around a few blocks to get it to work. However, if you have any issues, please feel free to comment.