Last updated on March 14th, 2021 at 07:31 am

You can install Home Assistant using several different methods. I tried them all, for months, so you don’t have to do the same. Finally, I decided to stay with Home Assistant Supervised method as one of the easiest and probably the best one in my personal opinion.

Let me show it to you!

How to Install Home Assistant Supervised – OFFICIAL WAY

What will you find in the article?

In today’s article we will talk about some Pros and Cons of all of the Official Home Assistant installation methods. After that I will install Home Assistant Supervised on a Raspberry Pi 4 as example.

Home Assistant Supervised can be also run on Intel-NUC, Odroid, and x86 PCs. Supervisor menu and Add-Ons are also working.

So stay tuned for the Pros and Cons of all of the official Home Assistant Installation methods or skip directly to the Home Assistant Supervised.

Let’s go…

What are the official ways to install Home Assistant?

At the moment there are 4 official and supported ways to install Home Assistant:

  • Home Assistant OS,
  • Home Assistant Container,
  • Home Assistant Core,
  • Home Assistant Supervised.

All of them have some Pros and Cons.

There are 4 official ways to Install Home Assistant
There are 4 official ways to Install Home Assistant

Home Assistant OS method

The first official and supported installation method is called Home Assistant OS.

Home Assistant OS comes in a form of a ready to use images, that could be used on a Raspberry Pi, Intel-NUC, Odroid and so on. Or you can use this Home Assistant OS image to create a new Virtual Machine with VirtualBox or other similar software, exactly as I’m showing in this article 👇

Install Home Assistant using VirtualBox on Windows/Linux/Mac

The Pros here are a lot:

You’ll get fully functional Home Assistant with Supervisor menu and Add-ons, everything is supported and regularly updated.

As cons imagine the following scenario: If you boot the Home Assistant OS image let’s say on a Raspberry Pi or Odroid – you cannot use that device for almost anything else!

You get Home Assistant and that’s it!

Additionally you can install only the available Add-ons in the Supervisor store and nothing more.

If you want to have a Home Assistant dedicated device, then Home Assistant OS is probably the best installation method for you! Otherwise keep reading.

Home Assistant Container method

The second official and supported method to install Home Assistant is called Home Assistant Container.

Just like the Home Assistant OS I have a detailed tutorial about it that you can check right here👇

The first method described in this article is about Home Assistant Container

Home Assistant Container is really easy to install, everything is supported and regularly updated. The only requirement is to have up and running Docker client and Internet connection for the initial part.

If you want to quickly spin a new Home Assistant instance and remove it later without any complications this is the best way. I’m constantly using the Home Assistant Container method for my YouTube videos and the articles here, where I usually test something and then wipe everything and start all over again.

The big cons in Home Assistant Container is that you won’t get the Supervisor menu and Add-ons when using this method of Home Assistant installation.

Home Assistant Core method

Third method of the official and supported Home Assistant installations is called Home Assistant Core.

It is somehow similar to the Home Assistant Container, but this time Python virtual environment is used instead of Docker.

Again you will not have the Supervisor store and Add-ons. Also few more steps are needed for installing and updating in comparison to the Home Assistant Container method.

This method is the origin of the Home Assistant. I started with Home Assistant Core when I was a Home Assistant noob (back then it was called differently). I did my first steps using Home Assistant Core and this is how I got hooked to Home Assistant.

Later, I switched to the other methods and never looked back, but this Python based Home Assistant will always have a special place in my RAM ❤️

Home Assistant Supervised method

And the Forth and final method is called Home Assistant Supervised.

We have Supervisor menu and Add-ons here and we have the freedom to install Home Assistant Supervised on a lot of devices, without the requirement to dedicate them for Home Assistant only.

For example you can have a Raspberry Pi with Raspberry Pi OS on which you can watch YouTube videos and to have Home Assistant working in the background simultaneously.

But let’s see a real Home Assistant Supervisor installation on a Raspberry Pi right now.

How to Install Home Assistant Supervised

I will use Raspberry Pi 4 with 4GB of RAM with Raspberry PI OS running on a microSD card. You can use the same or you can use a SSD instead – exactly as described in this article👇

Boot Raspberry Pi 4 from SSD instead of miroSD card for better performance and stability.

Of course you can use totally different device like Odroid, Intel NUC or even x86 or x86-64 desktop PC with Intel or AMD CPUs. As long as the device is having Debian or Debian based Linux distribution installed.

Home Assistant Supervised dependencies

These are dependencies needed to install Home Assistant Supervised.

  • Docker CE >= 19.03
  • Systemd >= 239
  • NetworkManager >= 1.14.6
  • AppArmor == 2.13.x (built into the kernel)
  • Debian Linux Debian 10 aka Buster (no derivatives)

Quick examination of the dependencies:

  • Docker – we will cover this in details in a minute.
  • Systemd – we already have this in Raspberry Pi OS (and all Debian based Linux Distributions).
  • NetworkManager and AppArmor will be installed/updated within less than a minute.
  • Debian linux – We will not meet this in this article! We will use Raspberry Pi OS, which is Debian based linux, just like Ubuntu, Linux Mint and tens or even hundreds of others. As a result we will se the following label inside our Home Assistant ⬇️
If you install Home Assistant supervised on something different than Debian you will see this  unsupported installation label.
If you install Home Assistant supervised on something different than Debian you will see this unsupported installation label.

Don’t worry too much about that label. I’m having my production / main Home Assistant installed that way with the same label for over a year now and I can assure you that nothing bad happened.

Of course, if you wish you can install Home Assistant Supervised on Debian with exact the same commands as I will use below and you won’t have that unsupported label. The choice is yours.

Let’s install the dependencies now.

Install Home Assistant Supervised dependencies

Connect to the device where Home Assistant Supervised will be installed or open a Terminal there and execute the following to update your Operating System:

sudo apt-get update && sudo apt-get upgrade -y

Install AppArmor, Network Manager and jq:

sudo apt-get install network-manager apparmor-utils jq -y

And reboot your device:

sudo reboot

We can continue with Docker installation now.

Install Docker

Docker is the next thing that is needed for Home Assistant Supervised.

I will show you how to install it on a Raspberry Pi. If you have different device go to docker.com and check which is the best way to install it for your setup.

For the Raspberry Pi, execute the following to get the official Docker installation script:

curl -fsSL https://get.docker.com -o get-docker.sh

After that, start the script and enjoy the ride:

sudo sh get-docker.sh

We have to add our linux user to the Docker group, but that is easy. If your user is not pi as in the example below, just change the last part of the command by replacing pi with your username:

sudo usermod -aG docker pi

When everything above is finished you can check if Docker is working by type the following:

docker --version

If you see some digits showing your Docker version, then you can continue forward as Mel Gibson in Brave Heart movie (but without the unhappy end).

Official Home Assistant Supervised installer script

Time to finally install Home Assistant Supervised.

We will use the official installer script coming from the Home Assistant developers. That means this script will most probably stay around for more than a minute.

At the end of the day everything is official here. Including my newsletter, where you can receive articles like this one on a weekly basis.

Now Let’s go:

Get the official Home Assistant Supervised installer script:

sudo curl -Lo installer.sh https://raw.githubusercontent.com/home-assistant/supervised-installer/master/installer.sh

Before you start the script, you have to choose your machine type as we are going to use that machine as installer script parameter.

These are the Home Assistant installer supported machine types:

intel-nucqemux86-64
odroid-c2raspberrypi
odroid-n2raspberrypi2
odroid-xuraspberrypi3
qemuarmraspberrypi4
qemuarm-64raspberrypi3-64
qemux86raspberrypi4-64
tinker
Supported Machine Types for the official Home Assistant Supervised installer.

Choose you machine and copy/paste the text from the table above at the end of the installer script.

For example if you have x86-64 computer (these are most of the modern Intel or AMD CPUs) you have to copy/paste the qemux86-64 after the –machine parameter in the command below. If you have Intel-NUC, get the intel-nuc and so on.

For Raspberry Pi 4, I will use the following command:

sudo bash installer.sh --machine raspberrypi4

After some time, the script will eventually ask you the following question:

Do you want to proceed with overwriting the /etc/network/interfaces file? [N/y]
Type "y" when you see that question during your Home Assistant Supervised installation.
Type “y” when you see that question during your Home Assistant Supervised installation.

Type “y” and wait for the installer script to finish. When that happen you will see some short instructions like these one bellow:

Try to open that address in a new browser, but it will needs some time to actually see any screen.

Firs setup will take some time. After a minute, or 5 or even 10 (be patient here) you can try to open your device IP on port 8123 (default Home Assistant port).

To install Home Assistant you should wait a bit for the installer script to finish.

When successful, you should see the following screen:

That means everything is fine and you just have to wait some more 🤣 (around 20 minutes) for everything to finish.

At the end you will see the Home Assistant welcome screen and initial wizard where you can create a Home Assistant user, set a location, add discovered devices and so on.

This is the Welcome Home Assistant wizard/screen where you can start flying.
This is the Welcome Home Assistant wizard/screen where you can start flying.

Home Assistant is running now what?

Now when you have your Home Assistant up and running it is possible and pretty normal to don’t know what to do next. Don’t worry, I’m here to help. You can check:

  • My YouTube Home Assistant Playlist – LINK
  • Or my Home Assistant category here in my website – LINK

Like something from the above links and try to implement it. If you face any difficulties you can always reach out in the comments or in my Discord server or in Twitter.

What is the best Home Assistant installation?

While you are still waiting for the Home Assistant Supervisor installation to finish. Can you tell me which of the official Home Assistant installation is best for you and why in the comments section below.

I promise to respond you back.

Home Assistant Supervised Final Thoughts

As every other method Home Assistant Supervised is having some Cons.

If you don’t want to see the unsupported label in Home Assistant you have to use exactly Debian Linux and nothing else. Although I didn’t find any differences between running Home Assistant on Debian and Raspberry Pi OS for example.

Also as you have full control over your OS you could easily break your Home Assistant installation by installing or removing some software. So you have to be a little bit more careful with that.

And pretty much that’s it, I didn’t find any other major cons of Home Assistant Supervised till now. If you know about some, let me know in the comments it will be very interesting to see them.

By the way If you are just entering the Smart Home world you could check my digital product called Smart Home – Getting Started Actionable Guide.

It will literally save your money and time – I promise!

Stay safe and don’t forget Home Smart, But Not Hard!

Thank you for reading, and I will see you in the next article.


43 Comments

Mesyu · 04/02/2021 at 2:24 pm

Interesting! I first installed RaspianOS on a Pi4 ssd and continued with IOTstack to end up with an unsupervised version. I wasn’t sure that is what I wanted and decided to start again using home assistant OS. It looks like the method you describe here is what I prefer best. I presume that IOTstack can be used to install all addons?

    Kiril · 04/02/2021 at 2:46 pm

    Actually, IOTstack and this method of Home Assistant Supervised installation are pretty much the same. Using IOTstack should be easier to install HA, but in my experience it is not very reliable and very often you have to troubleshoot and tweak somethings. The method that I’m describing here should be bullet proof.

DSG · 12/02/2021 at 9:09 am

Please help me
When installing Home Assistant Supervised, it returns an error:

[info] Install supervisor Docker container
invalid reference format

Tell me what made a mistake or where to look for information. I have already rummaged through everything that I could, I can not solve this problem (((

    Kiril · 15/02/2021 at 9:54 pm

    Hi, on what device and on what OS are you trying to install it?

Bobo · 15/02/2021 at 11:09 pm

I have the same problem with the invalid reference format.
Any idea how to fix this?

Bobo · 15/02/2021 at 11:12 pm

I’m on Ubuntu 20.10 on an older laptop with Intel CPU.

SNE · 19/02/2021 at 5:03 pm

How can I switch from a docker installation to the supervised method without loosing any data from the previous installation??

    lukas · 22/02/2021 at 9:48 pm

    yea i d like to know that aswell 🙂

      Kiril · 22/02/2021 at 10:35 pm

      Hi Lukas, I tried to answer the SNE question. Check it out!

    Kiril · 22/02/2021 at 10:34 pm

    Full backup, with history and everything is only possibly with snapshots, but you can try to backup and restore, your config folder (all yaml files inside) and you will be close to full replication

Louis · 25/02/2021 at 2:43 am

Walked through this guide a few times with no luck with given commands. After sending the sudo bash installer script, during the “Install supervisor docker container” it breaks with
Error response from daemon: Get https://registry-1.docker.io/v2/: dial: tcp: lookup registry-1.docker.io on 10.0.0.1:53 dial udp 10.0.0.1:53: connect: network is unreachable. The only method I’ve found around this is using a previous version of git with kwanga or something. Still have yet to correct the solution here. Running rpi4-8GB fresh raspbian lite image.

    Kiril · 25/02/2021 at 8:22 am

    That is really strange I’m using exactly RPI4-8GB on Raspberry OS but not lite. I also have it on RPI4-4GB and it worked without any issues. Can you try to install it when you are connected via LAN cable and not WiFi?

      Anon · 02/03/2021 at 12:42 pm

      Incase anyone else stumbles onto this issue while searching. I found the issue to be the pi power supply providing low voltage triggering it to drop wifi.
      A better power supply and Ethernet fixed the issue

        Kiril · 06/03/2021 at 8:06 am

        It is great that you share that info Anon. Much appreciate it! And I’m glad that you fixed your issue.

        Uwe · 17/04/2021 at 1:15 am

        I had the same problem, even though I used the official power supply. I fixed it by using LAN cable instead of Wi-Fi.

          Kiril · 19/04/2021 at 6:48 pm

          Yes, LAN cable can help if you loose connection during installation. After the installation finish you can switch back to Wi-Fi

    Sako · 22/03/2021 at 10:53 pm

    Had a similar problem where the script would crash after printing [info] Install supervisor Docker container with a seemingly random network error when connecting to https://registry-1.docker.io/v2/

    Found a solution here:
    https://forums.docker.com/t/tls-handshake-timeout-pulling-from-docker-hub-on-a-raspberry-pi-1-on-docker-17-03/53614
    Its reduce the number of parallel downloads of the docker daemon to 1

    /etc/docker/daemon.json
    {

    “max-concurrent-downloads”: 1
    }

      Kiril · 23/03/2021 at 9:30 pm

      Thank you very much for the links and the fix that could help if someone face the same issue.

Matej · 01/03/2021 at 11:58 am

Hi,
I followed your guide and successfully installed HomeAssistant on Raspbian Buster OS, running on RaspberryPi 3 device. The reason I wanted to have installation that way (and not using HA OS) is, that I would like to use my Raspberry 3 with HomeAssistant as a VPN client and I also want to set up specific firewall rules on this machine. Wireguard plugin allows only server installation, not client installation.

So, everything is working fine, but when I reboot my device (through command line – ssh or. through web GUI of HomeAssistant), Home Assistant does not start up again.

docker ps -a shows that almost all containers exited (except hassio_observer), so I say (in ssh terminal)

docker restart homeassistant
docker restart hassio_multicast
docker restart hassio_observer
docker restart hassio_cli
docker restart hassio_audio
docker restart hassio_dns
docker restart hassio_supervisor

The everything was working, but after a couple of restarts I can see docker processes running, but web GUI is not accessible. Any idea what could be wrong?

    Kiril · 06/03/2021 at 8:05 am

    Sorry, I don’t know that seems that some kind of a Docker issue to me. Try to downgrade it to latest version 19.xx or upgrade it to the latest if you are not.

green · 12/03/2021 at 8:07 am

Hi Kiril,

It works perfectly on my RPi4, but I cant get SSL to work, I’ve tried the Duckdns add-on and manual set up. Did you set up remote access?

green · 12/03/2021 at 8:35 am

Never mind, fixed it. Installed the duckdns add-on and added this to my configuration.yaml

http:
ssl_certificate: /ssl/fullchain.pem
ssl_key: /ssl/privkey.pem

    Kiril · 12/03/2021 at 8:36 am

    Good job Enjoy!

Andy · 14/03/2021 at 3:07 am

Cheers mate, very straightforward and to the point guide – was trying to make sense of the installation on the official web, but ended up here. Thanks!

    Kiril · 14/03/2021 at 7:35 am

    I’m very happy to hear that I was helpful. Feel free to check my other articles as well!

green · 23/03/2021 at 6:14 am

Any way to get this installed on a Raspberry Pi Zero W? it errors out after the NetworkManager reboot.

    Kiril · 23/03/2021 at 9:32 pm

    Check the Sako comment below with the reducing concurrent downloads parameter. Maybe this fix will help you as well.

green · 23/03/2021 at 7:55 am

Oops, sorry about double post

    Kiril · 23/03/2021 at 9:33 pm

    No issue, I deleted one of the posts. Let us know what happened with the Sako fix.

      green · 25/03/2021 at 5:44 am

      Sako fix didnt work. I have noted that everytime I try and it gets to the NetworkManager restart line the ip address gets renewed with a new one, so i have to open a new putty session. I will try with a monitor attached.

      green · 25/03/2021 at 6:58 am

      So with the Zero W connected to a monitor and Sado’s Fix, I get further.

      Next I get an error at
      [info] Install supervisor Docker container
      invalid reference format

      I’m using “sudo bash installer.sh –machine raspberrypi

green · 25/03/2021 at 8:00 am

So I read through the installer.sh and the only versions to install are i368, Armhf and Armv7, both of which wont work with an original Raspberry Pi or the Zero/Zero W.

It looks like it redirects Armv6 versions to Armhf, but i’m no expert.

Looked for manual install version but can’t find any

    Kiril · 28/03/2021 at 6:53 pm

    Let us know if you find a fix/solution for the Zero/Zero W. Good luck!

Michel · 28/03/2021 at 10:23 am

So i got everything up and running flawlessly on a Nuc with Debian. Thanks for that!

Updating Home assistant is pretty easy, but what is best practice to update Debian without possible breaking Home assistant? Do i let Home assistant running while i ssh into Debian and update it?
Or stop Home assistant, update Debian and restart the computer? Thanks in advance

    Kiril · 28/03/2021 at 6:46 pm

    In my humble opinion. You can update your OS while HA is running and then restart if needed.

Antonio · 30/03/2021 at 7:11 pm

Hi Kpeyanski, great video and great explanation. I have followed all the steps one by one, three times, and always get the same result HomeAssistant core-2021.3.4, not the supervised. How is this possible?. Many thanks in advance.

    Kiril · 02/04/2021 at 8:33 am

    Hi Antonio, I think you are just fine and you have the Supervised version which include HA core in it and that is perfectly normal. Just go to Configuration > Info and look what is written next to Installation Type. Let me know what happened.

Joe V · 08/04/2021 at 8:26 am

thanks for the guide. working well on pi4 64 bit version. however there is a new fire update out and it doesn’t seem to update from supervisor we interface. do we have to do the install script again to get the latest.?

    Kiril · 10/04/2021 at 12:01 am

    Strange, this should work. I’m with pi4 and Home Assistant updates are working without any issues from a very long time. Please check your Home Assistant logs for any errors.

Sleepy · 17/04/2021 at 2:49 am

I try to install the Supervised Version on a Pi2 with Ubuntu 20.04 LTS, which already runs PiVPN and Pihole/Unbound, but whenever i come to the part, where Docker should be installed, the script gives me this output:
# Executing docker install script, commit: 7cae5f8b0decc17d6571f9f52eb840fbc13b2737
+ sh -c apt-get update -qq >/dev/null
+ sh -c DEBIAN_FRONTEND=noninteractive apt-get install -y -qq apt-transport-https ca-certificates curl >/dev/null
+ sh -c curl -fsSL “https://download.docker.com/linux/ubuntu/gpg” | apt-key add -qq – >/dev/null
Warning: apt-key output should not be parsed (stdout is not a terminal)
+ sh -c echo “deb [arch=armhf] https://download.docker.com/linux/ubuntu focal stable” > /etc/apt/sources.list.d/docker.list
+ sh -c apt-get update -qq >/dev/null
+ [ -n ]
+ sh -c apt-get install -y -qq –no-install-recommends docker-ce >/dev/null
E: Package ‘docker-ce’ has no installation candidate

Following the Instructions for installation directly from docker doesnt work either and results in the same error. Any Ideas?

    Kiril · 19/04/2021 at 6:46 pm

    I think you should find 32-bit version of docker for raspberry pi. Is the version you are trying to install 32-bit?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.