Installing Home Assistant Supervised on Ubuntu 18.04.4


This guide is now deprecated and will no longer be updated or maintained. It is highly recommended to follow the Debian 10 guide HERE to have a supported Supervised install.

There is no need to use Ubuntu and continued changes being made to Home Assistant Supervised make its continued use at your own risk and it may fail to work at any time. Please do not post for support if you face an issue.

Ubuntu 18.04 does not have the minimum version of network-manager required by for a Supervised install, and as from supervisor 2020.12.06 you will get errors about having an “unsupported” installation and an “unhealthy” system. This may/will prevent you updating Home Assistant.


Installing Home Assistant Supervised on Ubuntu

This guide will help you to install Home Assistant Supervised, on almost any machine type you choose. This guide has been tested on a number of machines including, Intel NUC J5005, Dell Optiplex SFF 990 and Dell Optiplex USFF 780.

:warning: Please keep in mind that currently this installation method is not officially supported by the Home Assistant team, and therefore you are responsible for updating and managing updates and security on the base OS and no official support will be offered. This install method may cease to work at any time, so use at your own risk.

In this guide, you will be using Ubuntu Server 18.04.04 as the operating system. This type of installation is what is called “headless” and after the installation is complete, you will not need to have a keyboard, mouse or monitor attached (although you can if you prefer). You will manage and update the machine via terminal commands.

What is Home Assistant Supervised?

Home Assistant is a full UI managed home automation ecosystem that runs Home Assistant Core, the Home Assistant Supervisor and add-ons. It comes pre-installed on Home Assistant OS, but can be installed on any Linux system. It leverages Docker, which is managed by the Home Assistant Supervisor plus the added benefit of dozens of add-ons (think app store) that work natively inside the Home Assistant environment.

If you are new to Home Assistant, you can now proceed to Step 1. If you have an existing Home Assistant installation and need to know how to back up your current configuration, please see the document Backing up and Restoring your configuration located HERE

Section 1 – Install Ubuntu Server

1.1) Start by downloading Ubuntu Server 18.04.04 from HERE. This is a torrent file, so use your favourite torrent program.

1.2) While Ubuntu is downloading, you will need some other programs to help with the setup and installation. To burn the Ubuntu ISO image to a USB thumb drive, you will use a program called Rufus which can be downloaded from HERE. You will also use a piece of software called PuTTY, available HERE.

Putty is a free and open-source terminal emulator, serial console and network file transfer application. You will use Putty to execute commands on the Ubuntu machine from your Windows PC. (Use Terminal on a Mac).

1.3) You will now create a bootable USB drive using Rufus and the Ubuntu image you have downloaded. Insert a blank USB drive of at least 8gb into your PC, open Rufus and choose your USB from the drop-down menu. Now select the Ubuntu ISO image you downloaded, and click Start. If you get any prompts, select OK or Yes to continue.

1.4) Insert the USB you have just made into the new machine, connect a monitor, Ethernet cable, keyboard and mouse, and power on the machine. You will need to select the USB drive as the boot device, to do this, you will need to press something like F12 or DEL on your keyboard immediately when the machine is powered on.

1.5) The first screen you should be able to select from is the Welcome screen where you will select your language.

1.6) Next will be Keyboard Configuration. If you are using something other than English US, use the arrow keys on your keyboard to arrow up and select the correct type. When the correct selection is made, select DONE.

1.7) Next will be Network Connections. Make sure you can see an IP listed. Depending on your network configuration, it will show something like DHCPv4 The info you need to make a note of here is the IP as you will use this to connect to the machine later, in this case,

1.8) Next will be Configure Proxy. Skip this screen by selecting DONE, we do not need to enter anything.

1.9) Next will be Configure Ubuntu Archive Mirror. Skip this screen by selecting DONE, we do not need to enter anything.

1.10) Next will be Installer Update. We do not necessarily need to update the installer, so select CONTINUE WITHOUT UPDATING.

1.11) Next will be Filesystem Setup. Select USE AN ENTIRE DISK and then on the next screen select the disk you wish to use. Then on the next screen, select DONE and then CONTINUE.

1.12) Next will be Profile Setup. Enter your name, choose a name for your server (i.e. ubuntu-server) and enter a password. Make note of the username and password you choose here, this is what you will use to connect to the machine later.

1.13) Next will be SSH Setup. You will press SPACEBAR to place an X in the box next to INSTALL OPEN SSH SERVER, then arrow down to DONE.

1.14) Next will be Featured Server Snaps. We do not need to select anything on this screen, arrow down to DONE.

The installation will now continue automatically. When it has completed (5-15mins), you will see REBOOT at the bottom of the screen. Before rebooting, remove your USB drive, then press enter to reboot. While rebooting, you can also remove the keyboard, mouse and monitor as you will no longer need them.

Section 2 – Install Home Assistant Supervised

Now that you have Ubuntu installed, you can move on to installing Home Assistant Supervised.

2.1) First you will start by updating Ubuntu to make sure all the latest updates and security patches are installed. To do this you will use Putty to connect via SSH and copy and paste some commands. To connect to the Ubuntu machine via Putty, you will need the IP of the machine from Step 1.7, and the username and password you created from Step 1.12.

Open Putty and in the HOST NAME (OR IP ADDRESS) box, enter the IP of the Ubuntu machine, then select OPEN. You will now be prompted to enter your username (login as:) and password. Now that you have logged in, copy the following command and paste into Putty window by right clicking your mouse button. You may be asked to re-enter your password.

sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove -y

Depending on the speed of your internet connection, this could take anywhere from 2 to 20 minutes to complete. When finished, you will see the prompt.

2.2) Now the operating system is up to date, you can install Home Assistant Supervised. Copy each line of the below commands one at a time and paste them into the Putty window, and press ENTER. One of the following commands will execute a shell script as root, and some people may be concerned with the security risk. If you would like to read the script for piece of mind, click HERE

sudo -i

apt-get install -y software-properties-common apparmor-utils apt-transport-https avahi-daemon ca-certificates curl dbus jq network-manager socat

systemctl disable ModemManager

systemctl stop ModemManager

curl -fsSL | sh

curl -sL "" | bash -s

2.3) On a PC or NUC the installation time is generally under 5 mins, however it can take longer so be patient. You can check the progress of Home Assistant setup by connecting to the IP address of your machine in Chrome/Firefox on port 8123. (e.g.

Once you can see the login screen, the setup has been completed and you can set up an account name and password. If you are new to Home Assistant you can now configure any smart devices that Home Assistant has automatically discovered on your network. If you have an existing Home Assistant install and you have a snapshot or YAML files you wish to restore, refer to the document Backing up and Restoring your configuration.

That’s it, you have now installed Home Assistant Supervised on Ubuntu server and have SSH access to your machine to keep it up to date. It is recommended that you log into your machine using Putty at least once a month and use the following command to download security patches and keep the OS up to date.

sudo apt update && sudo apt dist-upgrade -y && sudo apt autoremove –y

Along with this guide, there is also associated documents available. These are essentially guides I use myself.

I welcome feedback on this guide, please feel free to tag me or PM if you have suggestions on how to make improvements.

Thank you to contributors, nickrout, finity and flamingm0e


For updates

Is there any way to start this install method from zero without a fresh ubuntu install ? something broke in my setup and homeassistant is starting but frontend keeps telling me connection refused. I read sooo many posts but could not find the right answer… SOething with IP adresses in the containers changed or somewhat. now i’d like to completely purge my docker with all containers and stuff but I think the installer script also installs some services i also want to remove to really start from scratch. any idea how to make this done?

P.S. Adorable post!

1 Like

This is great! So if I understood everything properly if I have HA core installed on the same ubuntu server. After performing the install I can stop the hassio-supervisor.service service, change the port in the configuration and start up again to look at both side by side? I know you may ask why would you want to do that but I like to understand things before switching. Like for example if I wanted to modify a HA core file in this install where would I navigate to? Currently I go to /srv/homeassistant/... to modify stuff.

  • If you are currently using Home Assistant Supervised , your files are located at /usr/share/hassio/homeassistant
  • If you are currently using Home Assistant Core , your files are located at /home/USERNAME/.homeassistant
  • If you are currently using Home Assistant Container , your files are located at /home/USERNAME/homeassistant
  • If you are currently using Home Assistant OS on a Pi, other SBC or in a VM, your files are located at /config
1 Like

these are config files I am talking about the actual home assistant core files for this supervisd install.

Thank you for posting this,

Does this install Home Assistant in Docker?

I previously followed an excellent guide in the past by Juantech for installing Ubuntu Server, HA & Docker but it now doesn’t work as the script to install Home Assistant has depreciated.

I followed this guide today and got HA running on a test machine

The last step of the other guide I followed was to install Portainer using the following commands:

docker run -d -p 9000:9000
–name portainer
–restart always
-v /var/run/docker.sock:/var/run/docker.sock
-v portainer_data:/data portainer/portainer

Is this still necessary with this tutorial?

Again thank you I panicked when I couldn’t proceed past installing HA lol

My installation is based on your guide with the difference I installed ubuntu desktop.
Let’s assume that I would like to have the same installation but with debian.
If you have sometime can you give us instructions how to “format” current setup and how to install ha in debian please?

The topic’s title indicates the instructions are for installing Home Assistant Supervised.

The other versions are:

Home Assistant
Home Assistant Core
Home Assistant Container

I believe you may be looking for instructions on how to install Home Assistant Container. It requires an existing Linux distro and docker. The installation instructions can be found here.

I should have a Debian version up later today

I’ve not seen that guide for some time, but from memory it was the old ‘’ install. If it used the script that no longer works, then it was essentially the same as this. I just forked the script and edited out the errors that stopped it working.

You don’t need Portainer, but I find it useful. Always be careful when using Portainer, you can cause yourself problems.

You could do that, but not something that I have done or recommend.


I would suggest, backup your YAML and storage files, format and start over.

1 Like

Thank you for the reply,

What’s the benefit of using Portainer and is the installation method I posted above the correct?

Portainer can be handy if you have an issue with a Docker container and want to access logs, delete and remove images and containers. If you don’t know what you are doing, you can cause issues for yourself by deleting the wrong container/image, so always use caution.

I install Portainer using this command.

sudo docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer
1 Like

Thank you for this excellent detailed guide. I did this type of install a while back and would have appreciated a guide like this at that time. I see where you linked to the “Backing up and Restoring your configuration” document earlier in the post, but I don’t see a link to the other document “Install Samba, Portainer and MQTT on Ubuntu Server 18.04.04”. Would it be possible for you to link to that, for completeness?

I’d like to be able to do all I normally do in a venv (modify system files) so I need to get my feet wet before making the switch.

In your post you had this directory as the config directory, do the HA core files also exist here? I am talking about files like this: core/homeassistant/components/neato at dev · home-assistant/core · GitHub and also the python libraries that get installed. Sometimes gotta dig deep to fix something real quick so I normally edit those.

Sorry, I misunderstood the initial question. It’s been a little while I have needed to get in and edit like this, but I believe this should get you to the correct location.

sudo docker exec -t -i homeassistant /bin/bash
cd /usr/src/homeassistant/homeassistant/components
1 Like

Thanks for the guide, good job! I hope it can repair my broken system :slight_smile:

On thing:
1.10) Next will be Installer Update . We do necessarily need to update the installer, so select CONTINUE WITHOUT UPDATING.
I assume you mean: We do not necessarily need to update the installer

Yes, thanks for the correction.

Ran this - worked excellent - Restored my config backup…all good.

Rebooted…but now nothing is in my docker. HA is not starting.

carsten@nuc-server:~$ sudo docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
carsten@nuc-server:~$ sudo docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

I am clearly missing something here to restart the docker after reboot of Ubuntu…please assist

Edit (thanks Jason):
I ran the curl command again…after reboot it came up fine. Also had remembered my restore…weird :slight_smile:

1 Like

Hey, great guide - thank you very much for this! I just installed it on my HTPC running Ubuntu LTS 18.04. I can see the containers in portainer as well. Now my questions:

  • Using the Google Drive backup should work in theory, right? I just that on my PI to restore and backup all of my config (link:

  • Are there any steps necessary to use a CC2531 stick (or Z-Wave stick) in order to use Zigbee2MQTT for example? Or should that work out of the box when I plug in my zigbee stick into my HTPC?

Yes. If you have made a snapshot, download it from Google drive to you PC and transfer it to /usr/share/hassio/backup on the new machine. Depending on what add-on you used, they may not all restore, but you can reinstall easily.

I didn’t have any issues moving from one machine to another with zigbee2mqtt when I restored a backup. You may need to reconfigure the address of the CC2531 in the zigbee2mqtt config.

1 Like