How To Install Home Assistant On Ubuntu In Just 5 Steps

Published Categorized as Command Line, Home Assistant, Linux
How To Install Home Assistant on Ubuntu

This article explains how to install Home Assistant on Ubuntu, probably the most commonly used version of Linux for desktop computers.

This installation method is best for those who specifically want to run Home Assistant on Ubuntu. The method is a container installation (without the add-on store), which must be self-managed and is therefore for advanced users.

If you just want to run Home Assistant on Linux hardware, Debian would be a better choice. You can follow the tutorial here for a Debian installation, it is for setting up a UTM virtual machine but will also work with a standard installation.

If you ended up here but want to install Home Assistant on Raspberry Pi, check out this guide instead.

There are several ways that we can install Home Assistant but the easiest way is to use Docker.

Don’t worry if you have never heard of it, this article will walk you through all of the necessary steps.

Table of Contents

  1. Can Home Assistant Run On Ubuntu?
    1. Why run Home Assistant on Linux?
  2. Prerequisites
  3. Installing Ubuntu for Home Assistant
    1. Update Ubuntu
  4. Installing Docker Engine
  5. Installing Home Assistant on Linux Using a Docker Image
  6. Configuring Home Assistant
    1. Find Your IP Address Using the Router Management Page
    2. Find Your IP Address Using the IP Terminal Command
    3. Home Assistant Onboarding
  7. Conclusion

Can Home Assistant Run On Ubuntu?

Yes, Home Assistant can be installed on Ubuntu, as well as other flavours of Linux.

The best way to do this is by installing it inside a Docker container using the following 5 simple steps:

Why run Home Assistant on Linux?

But why would you want to run Home Assistant on a full blown Linux distro rather than just a Raspberry Pi?

I recently migrated my Home Assistant setup over to Ubuntu for a couple of reasons and i’ll explain why.

There are several reasons you might want Home Assistant running on Linux. At the time of my first Home Assistant setup I only had an old Raspberry Pi 2 lying around. I built my initial setup on the Pi but shortly after I wanted more power.

I happened to have an old MacBook Pro gathering dust in a draw.

I had been on many emotional journeys with this machine in the 10 years of ownership and I didn’t have the heart to throw it in the trash, plus I hate to contribute towards electrical waste.

I decided that this machine would be perfect for my Home Assistant server, it had 8GB of RAM, a Core Duo 2 processor and an SSD drive so would outperform the Pi.

Best of all it was not going to cost me anything and at the same time I could do something for the environment. It was a little dented, scratched and beaten up but that didn’t matter because I was planning to hide it in the TV cabinet anyway.

As the only purpose of this machine is to run Home Assistant, I decided to make the machine headless and install Ubuntu server.

However this setup guide will work just fine with the standard desktop release too. I am sure it will also work with other versions of Linux so if you are using a different distro, let us know the results in the comments!

Prerequisites

You will need a copy of Ubuntu or Ubuntu Server and some hardware to run it on.

This tutorial is aimed at installation using Ubuntu. If you would prefer to use Debian, go ahead and check out this tutorial instead.

Installing Home Assistant will be carried out using the terminal command line, therefore you can use either Ubuntu or Ubuntu Server (without graphical user interface).

Step 1: Installing Ubuntu for Home Assistant

If you do not yet have Ubuntu up and running and intend on installing it, the process is very straightforward. It is completely free to download from the official website:

If you plan to install Ubuntu Server, it is worth knowing that there is also an ARM binary available.

If you need help installing Ubuntu, go ahead and check out these instructions.

Update Ubuntu

The first thing to do prior to setting up Home Assistant is to make sure Ubuntu is up to date.

Open up the terminal, then simply enter the following commands and allow any updates to install.

sudo apt-get update

sudo apt-get upgrade

Step 2: Installing Docker Engine

Docker is a clever little program that allows you to install and run applications within a ‘container.’

All of the dependencies required by the application can be packaged up into the container and are kept separate from the rest of the system.

This allows specific versions of libraries and other dependencies to be contained with their application and it prevents version conflicts in the system.

In order to install Docker Engine, we will follow the guide found on the official Docker site.

  1. From the terminal, go ahead and enter the following commands:

sudo apt-get install ca-certificates curl gnupg lsb-release

  1. Next we need to add the GPG key for Docker to our system. The purpose of this is for ensuring the validity of the download.

sudo mkdir -p /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

3. Use the following command to set up the repository.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  1. We are now ready to install docker, so go ahead and enter the following commands.

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

  1. Once Docker has finished installing we need to ensure that it will start when the system boots, so go ahead and enter this command.

sudo systemctl enable docker

  1. Finally we can test that Docker has been successfully installed by running the hello world command.

sudo docker run hello-world

If the installation was successful, you will receive the hello message from Docker:

Hello from Docker! This message shows that your installation appears to be working correctly.

Step 3: Installing Home Assistant on Linux Using a Docker Image

At this stage you should have Ubuntu up and running with Docker Engine installed.

Next we can install a container that has everything needed to run Home Assistant.

Home Assistant will be run from within this container, managed by the Docker Engine. This allows Home Assistant to be kept separate from the main system, preventing conflicts or other problems.

In order to install Home Assistant Container, we will use the guidance from the Linux installation guide on the official site.

  1. Go ahead and run the following command to install Home Assistant Container. Don’t let the complexity worry you too much, you can go ahead and copy & paste it directly into the terminal, then press enter.
    • /PATH_TO_YOUR_CONFIG points at the folder where you want to store your configuration and run it.
    • MY_TIME_ZONE is a tz database name, like TZ=America/Los_Angeles.

sudo docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=MY_TIME_ZONE \
-v /PATH_TO_YOUR_CONFIG:/config \
--network=host \
ghcr.io/home-assistant/home-assistant:stable

Step 4: Configuring Home Assistant

Firstly we need to know the IP address of our new Home Assistant server. There are several ways that we can do this.

Find Your IP Address Using the Router Management Page

If you have access to your router management page, you should easily be able to see the IP address for your machine here. In my case it’s 192.168.1.83.

Alternatively you can use a third party application like Fing.

Find Your IP Address Using the IP Terminal Command

The quickest and easiest way to find your IP address is by typing the following command into your terminal.

ip addr

Depending on whether you are connected by Ethernet or Wifi, look for a device named something like ‘enp0sxx‘ or ‘wlanx‘ and you should see your local IP address.

For example, here I am connected through Ethernet and my local IP address is 192.168.64.8.

Home Assistant Onboarding

Once we know the IP address of the Home Assistant server, we are able to connect and begin the onboarding process.

In order to connect to Home Assistant, navigate to your IP address and port 8123 in the browser:

http://192.168.64.8:8123

You will need to replace the address above with your own IP address. Depending on your network, you may also be able to use the generic address to access Home Assistant:

http://homeassistant.local:8123/

If all has been successful you will be greeted with the Home Assistant login page. Go ahead and create a username and password to log in to Home Assistant.

Home Assistant first login screen

Conclusion

It is certainly possible to run Home Assistant directly on Ubuntu, although it is not really officially supported nor a recommended way.

If you do not need specifically Ubuntu on your Home Assistant server then it would be better to use Debian instead.

If you really must run Ubuntu as your primary operating system, it would probably be better to run Home Assistant Supervised under Debian in a virtual machine.

Article Updates

8th August 2022: Tested installation with Home Assistant 2022.8.2 and Ubuntu Server Ubuntu 22.04.1. Screenshots updated to Home Assistant 2022.8.2.

Article first published February 7th 2020.