Installing Home Assistant


The following will take you through the steps required to install Home Assistant.

  1. Download the appropriate install option:

  2. Install Home Assistant:

    • Flash the downloaded image to an SD card using balenaEtcher. If using a Pi, we recommend at least a 32 GB SD card to avoid running out of space. On Virtual machine platforms, provide at least 32 GB of disk space for the VM.
    • Load the appliance image into your virtual machine software. Choose 64-bit Linux and UEFI boot.
  3. Optional - set up the Wi-Fi or static IP. There are two possible places for that:

    • on a blank USB stick with a FAT32 partition having partition label CONFIG, while in its root directory, create the network/my-network file, or
    • on the Home Assistant SD card’s first, bootable partition (labeled hassio-boot, might not be auto mounted in Linux) create the CONFIG/network/my-network file.

    For the content of this file, follow the Home Assistant Operating System howto.

  4. For image-based installs insert the SD card (and optional USB stick) into the device.

  5. Turn on your device or virtual appliance. On first boot, it downloads the latest version of Home Assistant which takes around 20 minutes (slower/faster depending on the platform and your Internet connection).

  6. You will be able to reach your installation at http://homeassistant.local:8123 (if your router supports mDNS, otherwise see below).

  7. It is important to provide yourself proper access, including the Home Assistant CLI tools. Both the Samba add-on and the SSH add-on should be the first add-ons you should install, before making changes to the configuration in the /config/ folder. From the UI choose Supervisor, which is located in the sidebar and then the add-on store.

We used hassio.local in the past, if you have a system that is installed before this naming change, you might need to use hassio.local instead of homeassistant.local.

If your router doesn’t support mDNS, then you’ll have to use the IP address of your Pi instead of homeassistant.local. For example, http://192.168.0.9:8123. You should be able to find the IP address of your Pi from the admin interface of your router.

If you are using a Raspberry Pi please remember to ensure you’re using an appropriate power supply with your Pi. Mobile chargers may not be suitable since some were only designed to provide just enough power to the device it was designed for by the manufacturer. Do not try to power the Pi from the USB port on a TV, computer, or similar.

Now you can configure your install.

Updating a Home Assistant installation

Best practice for updating a Home Assistant installation:

  1. Backup your installation, using the snapshot functionality Home Assistant offers.
  2. Check the release notes for breaking changes on Home Assistant release notes. Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (CTRL + f) and search for Breaking Changes.
  3. Check your configuration using the Check Home Assistant configuration add-on.
  4. If the check passes, you can safely update. If not, update your configuration accordingly.
  5. Select Dashboard from the Supervisor menu, and then select Update.

Run a specific version on Home Assistant

SSH to your Home Assistant system, or connect to the console, and run:

ha core update --version=0.XX.X

Run the beta version on Home Assistant

If you would like to test next release before anyone else, you can install the beta version released every three weeks:

  1. Backup your installation, using the snapshot functionality Home Assistant offers.
  2. Check the Home Assistant Beta release notes for breaking changes. Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (CTRL + f) and search for Breaking Changes.
  3. Select System tab from the Supervisor menu, then select Join Beta Channel under Supervisor, then select Reload.
  4. Select Dashboard tab from the Supervisor menu, and then select Update.

Alternative: install Home Assistant Supervised on a generic Linux host

You can also install Home Assistant on a Linux operating system of choice, called Home Assistant Supervised.

Home Assistant Supervised, will still give you access to most features Home Assistant has to offer, including add-ons.

The packages you need to have available on your system needed to Home Assistant may vary.

Debian/Ubuntu

  • apparmor-utils
  • apt-transport-https
  • avahi-daemon
  • ca-certificates
  • curl
  • dbus
  • jq
  • socat
  • software-properties-common

Optional:

  • network-manager

Without the NetworkManager, you will be not able to control your host network setup over the UI. The modemmanager package will interfere with any Z-Wave or Zigbee stick and should be removed or disabled. Failure to do so will result in random failures of those integrations. For example, you can disable with sudo systemctl disable ModemManager and remove with sudo apt-get purge modemmanager

Arch Linux

  • apparmor
  • avahi
  • ca-certificates
  • curl
  • dbus
  • docker
  • jq
  • socat

You also need to have Docker-CE installed. There are well-documented procedures for installing Docker on Ubuntu at Docker.com, you can find installation steps for your Linux distribution in the menu on the left.

Some distributions, like Ubuntu, have a docker.io package available. Using that package will cause issues! Be sure to install the official Docker-CE from the above-listed URL.

Docker is not always ready with a release when a new Ubuntu version is out. Check if your version of Ubuntu is supported by Docker here.

Preparation

To prepare your machine for the Home Assistant installation, run the following commands:

For Ubuntu:

add-apt-repository universe

Debian/Ubuntu:

sudo -i
apt-get install software-properties-common
apt-get update
apt-get install -y apparmor-utils apt-transport-https avahi-daemon ca-certificates curl dbus jq network-manager socat
systemctl disable ModemManager
curl -fsSL get.docker.com | sh

The following script will then install Home Assistant on a variety of operating systems and machine types.

curl -sL "https://raw.githubusercontent.com/home-assistant/hassio-installer/master/hassio_install.sh" | bash -s

Some installation types require flags to identify the computer type, for example, when using a Raspberry Pi 3, the flag -- -m raspberrypi3 is required. The install script would then look like this:

curl -sL "https://raw.githubusercontent.com/home-assistant/hassio-installer/master/hassio_install.sh" | bash -s -- -m raspberrypi3

Other machine types

  • intel-nuc
  • raspberrypi
  • raspberrypi2
  • raspberrypi3
  • raspberrypi3-64
  • raspberrypi4
  • raspberrypi4-64
  • odroid-c2
  • odroid-cu2
  • odroid-xu
  • orangepi-prime
  • tinker
  • qemuarm
  • qemuarm-64
  • qemux86
  • qemux86-64

See the hassio-installer GitHub page for an up-to-date listing of supported machine types.

If you can not find your machine type in the list, you should pick the qemu release. i.e., qemux86-64 for a normal 64-bit Linux distribution, or qemuarm-64 for most modern ARM-based target like Raspberry Pi clones, or TV boxes.

When you use this installation method, the core SSH add-on may not function correctly. If that happens, use the community SSH add-on. Some of the documentation might not work for your installation either.

A detailed guide about running Home Assistant as a virtual machine is available in the blog.