Installing Home Assistant on Ubuntu

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

wget https://github.com/home-assistant/os-agent/releases/download/1.6.0/os-agent_1.6.0_linux_x86_64.deb

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.

Downloading and Modifying the Home Assistant package for Ubuntu

8. To get Home Assistant to run on Ubuntu, we must make changes to the “homeassistant-supervised” package we will be using.

The main change we must make is removing “sysmted-resolved” as a dependency. This is installed by default and goes by the name “resolvectl” with recent versions of Ubuntu.

Start by creating a directory where we can unpack the Home Assistant package.

mkdir /tmp/homeassistant-supervised

9. After creating the directory, change to it by using the following command.

cd /tmp/homeassistant-supervised

10. We now need to download the Home Assistant package to our Ubuntu system using the following command.

wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb

11. We can now use the “ar” tool we installed earlier in this guide. Don’t worry. This process isn’t that complicated, and it is reasonably easy to put a Debian package back together.

ar x homeassistant-supervised.deb

12. Now extract the “control.tar.xz” archive. This archive is where the metadata of a Debian package is stored.

You can extract this archive using the command below in the terminal.

tar xf control.tar.xz

13. The next step is to open up the “control” file within the nano text editor by using the following command.

nano control

14. Within this file, find the line that starts with the following.

Depends:

You should see something like the following at the end of the above line. You will want to remove it.

, systemd-resolved

15. After removing “systemd-resolved” from the “Depends:” line, it should look similar to what we have shown below.

Depends: curl, bash, docker-ce, dbus, network-manager, apparmor, jq, systemd, os-agent, systemd-journal-remote

16. Once you have made the changes to the control file, save and quit by pressing CTRL + X, followed by Y, then the ENTER key.

17. Now, repack the control archive using the following command within the terminal.

tar cfJ control.tar.xz postrm postinst preinst control templates

18. Finally, all we need to do now is repackage the Home Assistant package so we can install it to our Ubuntu system.

To repackage everything, run the command below in the terminal.

ar rcs homeassistant-supervised.deb debian-binary control.tar.xz data.tar.xz

Installing Home Assistant Itself to Ubuntu

19. With the Home Assistant Supervised package downloaded and modified 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 ./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.

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

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

sudo reboot

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

For example, our instance of this software is available to us by going to the following web address in a web browser.

http://192.168.0.83:8123

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 “FINISH” button.

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.

Conclusion

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.

If you found this tutorial helpful, you can check out our guides on Home Assistant or our many Ubuntu tutorials.

Weekly Updates Straight To Your Inbox

Receive our Raspberry Pi projects, coding tutorials, Linux guides and more!

Subscribe