Install Home Assistant on Ubuntu: A Step-by-step guide (2024)

Installing Home Assistant at home is an interesting project to start playing with home automation. Once connected to all your smart devices, you’ll have the control and can do anything you want easily. In this tutorial, I’ll show you each step to get it running, so you can begin automating your home.

Home Assistant is available as a Docker container on Ubuntu, making it easy to install and allowing us to use this application with other services installed on the same system.

I know that not everybody is used to Docker, that’s why I created this guide, where I will explain everything step-by-step. Just follow this tutorial to get Home Assistant running on your system in no time.

Linux doesn’t have to be intimidating. With my e-book, Master Linux Commands, you’ll uncover the secrets of the terminal in a fun, step-by-step journey. From basics to scripts, get ready to level up your Linux skills. Oh, and did I mention the handy cheat sheet you get as a bonus?

Home Assistant Installation with Docker

There are many ways to install a service like Home Assistant on Linux, but when Docker is an option I often recommend it, as you are guaranteed it will work after a straightforward installation. No compilation error or packages conflicts is expected with it :-).

Update your system

I’m testing this setup on the latest Ubuntu version available at the time of writing (22.04), but it should work on any Debian-like distribution. If you are using other Linux systems like Manjaro or Fedora, you’ll need to adapt some of these commands.

Before anything else, make sure your system is up-to-date, to avoid any issue during the installation.
Open a terminal or connect to your server via SSH and type the following commands:
sudo apt update
sudo apt upgrade

You can obviously use the desktop interface to do the same thing if you have a desktop environment installed.

If there are a lot of updated packages, a reboot is recommended before going further:
sudo reboot

Are you a bit lost in the Linux command line?Check this article first for the most important commands to remember and a free downloadable cheat sheet so you can have the commands at your fingertips.

Install Curl

Curl is a command line we’ll use on the next step to install Docker. It’s not installed by default on Ubuntu, so you may need to install it before going further:
sudo apt install curl

Your Go-To Linux Command Reference!
Download your exclusive free PDF containing the most useful Linux commands to elevate your skills!
Download now

Install Home Assistant on Ubuntu: A Step-by-step guide (1)

How to Install Docker

If you never used Docker previously, you first have to install it on your computer.

The easiest way to install Docker on Linux is to use this command:
curl -sSL | sh

You don’t need to use sudo, the script will do it for you. Basically, this command will add a new repository to your APT sources, and install the packages from there.

Join Our Community!

Connect, learn, and grow with other Raspberry Pi enthusiasts. Support RaspberryTips and enjoy an ad-free reading experience. Get exclusive monthly video tutorials and many other benefits.

Learn more

Install Home Assistant on Ubuntu: A Step-by-step guide (3)

If you are new to this, I recommend reading my complete guide about Docker first. Just to make sure you understand what you’re doing here. It’s oriented for Raspberry Pi users, but the idea is the same on Ubuntu.

Also, if you want to give the permission to your normal user to use Docker commands directly, without sudo, you can run this command to add it to the docker group on your system:
sudo usermod -aG docker $USER
You need to log out and log in again to apply changes (same thing on Desktop and SSH).
You can test if it’s working with:
docker ps

Install the Home Assistant container

Now that Docker is set up on your system, you can follow the documentation and create a new container with Home Assistant. Here is the command syntax to do this:

docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-v /PATH_TO_YOUR_CONFIG:/config \
--network=host \

Yes, that is a big command, and you need to adjust it for your system:

  • Replace MY_TIME_ZONE with your current timezone. The format is Country/City.
    For example: TZ=Europe/Paris
  • Replace PATH_TO_YOUR_CONFIG with the folder where you want to store the configuration files.

In my case, I just used this command:

docker run -d \--name homeassistant \--privileged \--restart=unless-stopped \-e TZ=Europe/Paris \-v /home/pat/hass:/config \--network=host \
Install Home Assistant on Ubuntu: A Step-by-step guide (4)

After doing this, the container will start and the web interface will be available at the same address as with the complete setup. So, you can continue this tutorial to find out how to access it and start using Home Assistant.

Note: It worked fine the first time I tried, but after a second try on another VM, I got this error:
“docker: Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock”
I fixed it with:
sudo chmod 666 /var/run/docker.sock

Your Go-To Linux Command Reference!
Download your exclusive free PDF containing the most useful Linux commands to elevate your skills!
Download now


Updating Home Assistant with the Docker installation method is a bit tricky. You can’t just run apt upgrade and hope that you’ll keep it up-to-date. After reading the documentation, the only way to update it seems to remove the container and create a new one with the new version.

Here is the command to run (in this order):
docker pull
docker stop homeassistant
docker rm homeassistant

Then, you can use the same command as during the installation to recreate the container. Make sure to use the same path for the configuration folder if you don’t want to start from scratch after each update.

Getting Started with Home Assistant

Once Home Assistant installed, it’s now time to connect it to all your smart devices and start having fun with it!

First access to the web interface

Whatever the installation method you chose, Home Assistant will start a web interface on the port 8123 of your system. You can generally it access it with http://localhost:8123 or http://IP_ADDRESS:8123.

Install Home Assistant on Ubuntu: A Step-by-step guide (5)

You should get a form, as seen on the above screenshot, asking you to create the first user account.
Then you will be asked a few questions to customize your setup:

  • Give a name to your Home Assistant installation.
  • Set your location, timezone, unit system and currency.
  • Check the boxes corresponding to the data you are ready to share with the developers (or skip this screen).
  • The wizard will then scan your network, and offer you to quickly add any supported smart devices:
    Install Home Assistant on Ubuntu: A Step-by-step guide (6)
  • Just click on the one you want to add, or click “Finish” to do this later.
    In my case, it detected most of the ones that were connected during the installation (lights, smart plugs and NAS).
  • Adding each device may require additional steps. For example, for Philips Hue lights, you need to press the button on the hub to allow Home Assistant to control it, and then assign each light to a room.
  • You can obviously click “More” to add additional integrations (like websites or things that have not been detected automatically), but I recommend doing this later in the full interface.

Once this onboarding wizard completed, you should get access to the full interface, with a nice dashboard including the integrations you set up:

Install Home Assistant on Ubuntu: A Step-by-step guide (7)

You can now use this interface to manage your smart devices. For example, I can switch off or on the kitchen light by clicking the corresponding button. But Home Assistant goes way further than that.

Add more integrations

First, make sure to set up all your smart devices on this interface. You can use the configuration item in the left menu to add new ones:

  • Click on Configuration and then Devices & Services.
  • You’ll get the same list as during the onboarding process, but you can also add new integrations.
  • Home assistant is compatible with a lot of services related to home automation.
    Here are a few examples: weather websites, network devices (Unifi, Synology, …) , cloud services (Google, Apple, …), robots (vacuum), smart plugs (home, car, …), etc.
    You’ll get the full list when you click on “Add Integration”, it’s insane all the things you can monitor and use in your automations.
  • You’ll then get extra steps depending on the integration you want to add.
    For example, to connect to a weather API, you’ll generally need an API key (you can often get one for free, just by creating an account on their website).
    For a robot vacuum, you’ll probably need to press a button on it. Etc.

Try to add a few integrations. Obviously, Home Assistant is an exciting project when you have many smart devices and can make them work together by creating some automation (ex: when I open the door, light on the living room and after 10s start my favorite song). But even with a few of them and addition web services, you can already build some nice dashboards.

Create a new dashboard

By default, Home Assistant will create a basic dashboard (Overview), and another one named “Energy”. But you can edit them, delete them or create new ones. Here is how to do this:

  • Go to Configuration > Dashboards.
  • Choose a title and an icon:
    Install Home Assistant on Ubuntu: A Step-by-step guide (8)
  • Then click on it in the left menu to open it.
  • You can now click in the top-right corner menu and choose “Edit Dashboard” to customize it.
  • From there, you can do everything you want: add new cards, delete some, move the existing ones up and down, etc.
  • For each card, there are many templates you can use to format the data differently (button, calendar, history graph, gauge, etc.).
    Install Home Assistant on Ubuntu: A Step-by-step guide (9)
  • After choosing a template, you’ll need to pick the exact value you want to display on it.
    For example, in my Weather dashboard, I can choose to display the temperature, precipitation, UV index, etc.
    Install Home Assistant on Ubuntu: A Step-by-step guide (10)

You may think it’s complicated while reading this, but try to use it. It’s pretty intuitive, so I’m sure you’ll understand everything quickly. Start with something you really want to have on your dashboard, and find the best way to display the value.

Create your first automation

Obviously, Home Assistant is not only a way to have nice dashboards and replace several apps with one. It’s also the most effective way to automate your home.

Automation is a process that will run automatically when a trigger is detected:

  • If the inside temperature drop below 20°C, turn on the heater.
  • When motion is detected in the bedroom, turn on the wall light.
  • If the wind is over 60 km/h, close the shutters.
  • Etc.

Creating an automation is not complicated once you get the idea. Find something simple you want to try, and follow these steps to configure it:

  • Go to Configuration > Automations.
  • Click on “Add Automation”.
  • Change the automation name to something you’ll remember.
    A one sentence telling exactly what it does is best.
  • In the triggers part, set the device that will be used to start the automation.
  • Then set the exact trigger sensor and value that will start the automation.
    For example, I tested with AccuWeather (a weather web service), and tell that when the cloud ceiling is below a certain threshold, it will start an automation to light on the house.
    But you can simply use the “Sun” trigger, and turn on the lights on sunset for example.
    Install Home Assistant on Ubuntu: A Step-by-step guide (11)
  • You can add conditions in the next section if needed.
    Dumb example: don’t turn on the kitchen if the light is already on.
  • Then, set the actions that should be triggered when the conditions are fulfilled.
    In my case: Turn on the kitchen light, for example.
    You may also tweak other settings like the brightness for lights, etc.

Try to create something simple first, and check if it’s working. Depending on the smart devices and integrations you set up, this will be more or less easy to test. The possibilities are endless, just try to think of something useful for your house.

Your Go-To Linux Command Reference!
Download your exclusive free PDF containing the most useful Linux commands to elevate your skills!
Download now

Final Thoughts

Overall, Home Assistant is a great application. The installation is pretty straightforward, and you can do almost anything with it. The interface is intuitive, it’s just getting complicated if you try to build complex automations with multiple smart devices interconnected.

If you have smart devices, but find they are not that smart, and you still need to do many tasks manually, Home Assistant could be what’s missing in your home. Try to install it and find some ways to make it useful, you’ll have an excuse to spend more time on your computer :-).

Your Go-To Linux Command Reference!
Download your exclusive free PDF containing the most useful Linux commands to elevate your skills!
Download now

🛠 This tutorial doesn't work anymore? Report the issue here, so that I can update it!

Reminder: Remember that all the members of my community get access to this website without ads, exclusive courses and much more. You can become part of this community for as little as $5 per month & get all the benefits immediately.

You may also like:

  • Master Linux Commands (eBook)
  • The 5 fastest ways to find a file on Linux
  • Snap vs APT: what's the difference?

Additional Resources

Overwhelmed with Linux commands?
My e-book, “Master Linux Commands”, is your essential guide to mastering the terminal. Get practical tips, real-world examples, and a bonus cheat sheet to keep by your side.
Grab your copy now.

VIP Community
If you just want to hang out with me and other Linux fans, you can also join the community. I share exclusive tutorials and behind-the-scenes content there. Premium members can also visit the website without ads.
More details here.
Need help building something with Python?
Python is a great language to get started with programming on any Linux computer.
Learn the essentials, step-by-step, without losing time understanding useless concepts.
Get the e-book now.

Install Home Assistant on Ubuntu: A Step-by-step guide (2024)


How to install Home Assistant on Ubuntu command line? ›

Install Home Assistant Core on Ubuntu 22.04
  1. apt update && apt upgrade. ...
  2. add-apt-repository ppa:deadsnakes/ppa.
  3. apt update.
  4. apt install wget build-essential libncursesw5-dev libssl-dev. ...
  5. apt install python3.11 python3.11-dev python3.11-venv python3-pip.
Aug 29, 2023

How to install Ubuntu Linux complete step by step guide? ›

Install Ubuntu desktop
  1. Download an Ubuntu Image. You can download an Ubuntu image here. ...
  2. Create a Bootable USB stick. ...
  3. Boot from USB flash drive. ...
  4. Installation Setup. ...
  5. Type of installation. ...
  6. Create Your Login Details. ...
  7. Choose your Location. ...
  8. Ready to install.

Which Linux is best for Home Assistant? ›

I'd do a supervised install on debian bookworm. This is the approach I've used for years. With this approach you can run other things on the OS if you need to. People will indicate that running things on the base OS makes the system non-supported, but the HA software doesn't complain.

Which version of Ubuntu for Home Assistant? ›

There's no officially supported “Ubuntu app” version of Home Assistant. I'll just add that I run my HA on a NUC as a VM. I use Ubuntu 22.04 Desktop as the Host OS and I use QEMU/KVM/Virtual-Manager as the VM.

How to install application on Ubuntu command line? ›

Installing with APT

Once in the package location folder, you can use the following command format sudo apt install ./package_name. deb . For example, to install virtual-box, you can run. Also, the command above will install all the required software dependencies for the package that you are installing.

What is the command for home in Ubuntu? ›

To navigate to your home directory, use "cd" or "cd ~" To navigate up one directory level, use "cd .." To navigate to the previous directory (or back), use "cd -" To navigate through multiple levels of directory at once, specify the full directory path that you want to go to.

How to install software in Ubuntu step by step? ›

Installing Software Packages via the Ubuntu Software Center
  1. Click the search icon (top-left), search for the software you wish to install (i.e., powershell), and select it to see its overview page. ...
  2. Next, review the detailed information to ensure the software meets your requirements, and click Install.
Jul 19, 2023

What is the command to install all packages in Ubuntu? ›

The apt command is a powerful command-line tool, which works with Ubuntu's Advanced Packaging Tool (APT). The commands contained within apt provide the means to install new software packages, upgrade existing software packages, update the package list index, and even upgrade the entire Ubuntu system.

How to install anything in Ubuntu using terminal? ›

  1. To install an application from the terminal in Ubuntu, you can use the apt-get command. ...
  2. This will download and install the vlc package and all of its dependencies.
  3. To uninstall an application, you can use the apt-get command with the remove option.
Dec 22, 2022

Which installation method is best for Home Assistant? ›

We recommend using Home Assistant Operating System. Other methods are available for experienced users for their specific needs, for example, running Home Assistant in a virtualized environment (e.g. Proxmox), or on top of an existing operating system (e.g. Windows, macOS, Linux):

What do I need to run Home Assistant? ›

What hardware is needed for Home Assistant 2023? As of 2023, the minimum hardware requirements haven't changed much. A Raspberry Pi 3B or higher, Odroid-N2, or an old laptop with at least 2GB of RAM should do the trick.

What OS to run Home Assistant on? ›

Home Assistant Operating System (formerly HassOS) is a Linux based operating system optimized to host Home Assistant and its Add-ons. Home Assistant Operating System uses Docker as its container engine. By default it deploys the Home Assistant Supervisor as a container.

How to get Home Assistant on Ubuntu? ›

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.

What is the best installation type for Ubuntu? ›

Note: We have two options here when it comes to the installation type: "Normal Installation" and "Minimal Installation." Minimal installation: This type of installation only contains basic functional applications. The most recommended way to learn about the Ubuntu desktop is to proceed with a "Normal Installation".

Which Ubuntu version is best? ›

List of Best Ubuntu Based Distros
  • POP! OS. ...
  • Elementary OS. ...
  • Kubuntu. ...
  • LXLE. ...
  • Lubuntu. ...
  • Xubuntu. ...
  • Ubuntu Budgie. As the name suggests, Ubuntu Budgie is a fusion of the traditional Ubuntu distribution and the innovative Budgie desktop environment. ...
  • KDE Neon. Much like Kubuntu, KDE Neon offers the KDE Plasma 5 desktop environment.
Jan 29, 2024

How do I access Home Assistant command line? ›

If you want to use the Home Assistant command line or an SSH client, you can do this through the Terminal & SSH add-on. The Terminal & SSH add-on provides the following functionalities: It provides a web terminal that you can access from the Home Assistant user interface.

How to install Ubuntu package from command line? ›

  1. apt-get install <package_name> This command installs a new package.
  2. apt-get build-dep <package_name> This command searches the repositories and installs the build dependencies for <package_name>. ...
  3. aptitude install <package_name> ...
  4. APT and aptitude will accept multiple package names as a space delimited list.
Jul 5, 2021

How do I install terminal on Home Assistant? ›

Home Assistant Add-on: Terminal & SSH
  1. This add-on is only visible to "Advanced Mode" users. To enable advanced mode, go to Profile -> and turn on Advanced Mode.
  2. Navigate in your Home Assistant frontend to Settings -> Add-ons -> Add-on store.
  3. Find the "Terminal & SSH" add-on and click it.
  4. Click on the "INSTALL" button.

How to install application from command line? ›

Install from cmd on a local machine
  1. Open the Start menu and type “cmd.exe.”
  2. Next, right-click “cmd.exe” from the “Programs” list, then proceed to click “Run as administrator.”
  3. After that, type the full path to the file's directory after the “cd” command. ...
  4. Type this command and then press “Enter”:
Jun 25, 2023


Top Articles
Latest Posts
Article information

Author: Delena Feil

Last Updated:

Views: 5269

Rating: 4.4 / 5 (45 voted)

Reviews: 84% of readers found this page helpful

Author information

Name: Delena Feil

Birthday: 1998-08-29

Address: 747 Lubowitz Run, Sidmouth, HI 90646-5543

Phone: +99513241752844

Job: Design Supervisor

Hobby: Digital arts, Lacemaking, Air sports, Running, Scouting, Shooting, Puzzles

Introduction: My name is Delena Feil, I am a clean, splendid, calm, fancy, jolly, bright, faithful person who loves writing and wants to share my knowledge and understanding with you.