home-assistant.io/source/_includes/installation/operating_system.md

Install Home Assistant Operating System

{% assign release_url = "https://github.com/home-assistant/operating-system/releases/download" %}

{% if site.installation.types[page.installation_type].board %}

Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience.

{% if page.installation_type == 'raspberrypi' %}

Suggested Hardware

We will need a few things to get started with installing Home Assistant. Links below lead to Amazon US. If you’re not in the US, you should be able to find these items in web stores in your country.

• Raspberry Pi 4 (Raspberry Pi 3 is ok too, if you have one laying around). Raspberry Pi are currently hard to come by, use RPilocator to find official distributors with stock.
• Power Supply for Raspberry Pi 4 or Power Supply for Raspberry Pi 3
• Micro SD Card. Ideally get one that is Application Class 2 as they handle small I/O much more consistently than cards not optimized to host applications. A 32 GB or bigger card is recommended.
• SD Card reader. This is already part of most laptops, but you can purchase a standalone USB adapter if you don't have one. The brand doesn't matter, just pick the cheapest.
• Ethernet cable. Required for installation. After installation, Home Assistant can work with Wi-Fi, but an Ethernet connection is more reliable and highly recommended.

{% endif %}

{% if page.installation_type == 'odroid' %}

Suggested Hardware

We will need a few things to get started with installing Home Assistant. Links below lead to Ameridroid. If you’re not in the US, you should be able to find these items in web stores in your country.

To get started we suggest the ODROID N2+, it's the most powerful ODROID. It's fast and with built-in eMMC one of the best boards to run Home Assistant. It's also the board that powers our Home Assistant Blue.

• ODROID N2+
• Power Supply
• CR2032 Coin Cell
• eMMC Module
• Case

If unavailable, we also recommend the ODROID C4 or ODROID XU4.

{% endif %}

{% if page.installation_type == 'tinkerboard' %}

Suggested Hardware

We will need a few things to get started with installing Home Assistant. Links below lead to Amazon US. If you’re not in the US, you should be able to find it in web stores in your country.

• Asus Tinkerboard S

{% endif %}

{% if page.installation_type == 'generic-x86-64' %}

Prerequisites

This guide assumes that you have a dedicated {{ site.installation.types[page.installation_type].board }} PC (typically an Intel or AMD-based system) available to exclusively run Home Assistant Operating System. The system must be 64-bit capable and able to boot using UEFI. Pretty much all systems produced in the last 10 years support the UEFI boot mode.

Summary

You will need to configure your {{ site.installation.types[page.installation_type].board }} PC to use UEFI boot mode, then write the HAOS (Home Assistant OS) disk image to your boot medium. There are two ways to do this listed below.

Configure the BIOS on your x86-64 hardware

To boot Home Assistant OS, the BIOS needs to have UEFI boot mode enabled and Secure Boot disabled. The following screenshots are from a 7th generation Intel NUC system. The BIOS menu will likely look different on your system. However, the options should still be present and named similarly.

1. To enter the BIOS, start up your x86-64 hardware and repeatedly press the F2 key (on some systems this might be Del, F1 or F10).

2. Make sure the UEFI Boot mode is enabled.

3. Disable Secure Boot.

4. Save your changes and exit.

The BIOS configuration is now complete.

Next, we need to write the Home Assistant Operating System image to the "boot medium", which is the medium your x86-64 hardware will boot from when it is running Home Assistant.

HAOS has no integrated installer that writes the image automatically, you must write it manually using e.g. Etcher.

Typically an internal medium like S-ATA hard disk, S-ATA SSD, M.2 SSD, or a non-removable eMMC is used for the x86-64 boot medium. Alternatively, an external medium can be used such as a USB SDD, though this is not recommended.

To write the HAOS image to the boot medium on your x86-64 hardware, there are 2 different methods:

1. Write the HAOS disk image from your desktop computer directly to the boot medium (e.g. using a USB to S-ATA adapter). If you can use this method, proceed to "Write the image to your boot medium" and follow all steps. If you have non-removable internal mediums or don't have the necessary adapter, try the next method instead.

2. Create a "live operating system" on a USB device running e.g. Ubuntu (how-to guide). Insert it into your system and boot the live operating system. Then follow from step 2 in "Write the image to your boot medium".

{% details "Ubuntu dependencies for Etcher" %}

When installing Etcher on Ubuntu you may need to install the fuse dependency first, to do this run the following commands in the terminal:

sudo add-apt-repository universe
sudo apt update
sudo apt install libfuse2

{% enddetails %}

{% endif %}

Write the image to your boot medium

1. Attach the Home Assistant boot medium ({{site.installation.types[page.installation_type].installation_media}}) to your computer. {% if page.installation_type == 'odroid' %} If you are using a Home Assistant Blue or ODROID N2+, you can attach your device directly. {% endif %}

2. Download and start Balena Etcher. You may need to run it with administrator privileges on Windows.

3. Select "Flash from URL".

4. Copy the URL for the {{site.installation.types[page.installation_type].board}} image which is: {% if site.installation.types[page.installation_type].variants.size > 1 %} {% tabbed_block %} {% for variant in site.installation.types[page.installation_type].variants %}

• title: {{ variant.name }} content: |

  {{release_url}}/{{site.data.version_data.hassos[variant.key]}}/haos_{{ variant.key }}-{{site.data.version_data.hassos[variant.key]}}.img.xz
  

  {% if variant.key == "odroid-n2" %} Guide: Flashing Odroid-N2 using OTG-USB {% elsif variant.key == "rpi4" or variant.key == "rpi3" %} (64-bit is recommended) {% endif %}

{% endfor %} {% endtabbed_block %} {% else %}

{% assign board_key = site.installation.types[page.installation_type].variants[0].key %}
{{release_url}}/{{site.data.version_data.hassos[board_key]}}/haos_{{ board_key }}-{{site.data.version_data.hassos[board_key]}}.img.xz

{% endif %}

Select and copy the URL or use the "copy" button that appear when you hover it.

1. Paste the URL for the {{site.installation.types[page.installation_type].board}} image into Balena Etcher and click "OK"
2. When Balena Etcher has downloaded the image, click "Select target"
3. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation
4. Click on "Flash!" to start writing the image
5. When Balena Etcher has finished writing the image you will see a confirmation

Start up your {{site.installation.types[page.installation_type].board}}

{% if page.installation_type == 'generic-x86-64' %}

• If you used your desktop system to write the HAOS image directly to a boot medium like an S-ATA SSD, connect this back to your {{ site.installation.types[page.installation_type].board }} system.

• If you used a live operating system (e.g. Ubuntu), shut it down and remove the live operating system USB device.

1. Plug in an Ethernet cable that is connected to the network.
2. Power the system on. If you have a screen connected to the {{site.installation.types[page.installation_type].board}} system, after a minute or so the Home Assistant welcome banner will appear in the console.

If the machine complains about not being able to find a bootable medium, you might need to specify the EFI entry in your BIOS. This can be accomplished either by using a live operating system (e.g. Ubuntu) and running the following command (replace <drivename> with the appropriate drive name assigned by Linux, typically this will be sda or nvme0n1 on NVMe SSDs):

efibootmgr --create --disk /dev/<drivename> --part 1 --label "HAOS" \
   --loader '\EFI\BOOT\bootx64.efi'

The efibootmgr command will only work if you booted the live operating system in UEFI mode, so be sure to boot from your USB flash drive in this mode. Depending on your privileges on the prompt, you may need to run efibootmgr using sudo.

Or else, the BIOS might provide you with a tool to add boot options, there you can specify the path to the EFI file:

\EFI\BOOT\bootx64.efi

{% else %}

1. Insert the boot medium ({{ site.installation.types[page.installation_type].installation_media }}) you just created.
2. Plug in an Ethernet cable that is connected to the network and power the system on.

{% endif %}

3. In the browser of your desktop system, within a few minutes you will be able to reach your new Home Assistant at homeassistant.local:8123.

If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at homeassistant:8123 or `http://X.X.X.X:8123` (replace X.X.X.X with your {{site.installation.types[page.installation_type].board}}’s IP address).

{% else %}

Download the appropriate image

• VirtualBox (.vdi) {% if page.installation_type == 'macos' %}
• KVM (.qcow2) {% endif %} {% if page.installation_type == 'windows' or page.installation_type == 'linux' %}
• KVM (.qcow2)
• Vmware Workstation (.vmdk) {% elsif page.installation_type == 'alternative' %}
• KVM/Proxmox (.qcow2)
• VMware ESXi/vSphere (.ova) {% endif %} {% if page.installation_type == 'windows' %}
• Hyper-V (.vhdx) {% endif %}

Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines we recommend installation Home Assistant OS directly on a Raspberry Pi or an ODROID.

Create the Virtual Machine

Load the appliance image into your virtual machine hypervisor. (Note: You are free to assign as much resources as you wish to the VM, please assign enough based on your add-on needs).

Minimum recommended assignments:

• 2 GB RAM
• 32 GB Storage
• 2vCPU

All these can be extended if your usage calls for more resources.

Hypervisor specific configuration

{% tabbed_block %}

• title: VirtualBox content: |

  1. Create a new virtual machine
  2. Select Type "Linux" and Version "Linux 2.6 / 3.x / 4.x (64-bit)"
  3. Select "Use an existing virtual hard disk file", select the unzipped VDI file from above
  4. Edit the "Settings" of the VM and go "System" then "Motherboard" and select "Enable EFI"
  5. Then go to "Network" "Adapter 1" choose "Bridged Adapter" and choose your Network adapter
  Please keep in mind that the bridged adapter only functions over a hardwired Ethernet connection. Using Wi-Fi on your VirtualBox host is unsupported.
  6. Then go to "Audio" and choose "Intel HD Audio" as Audio Controller.

  By default VirtualBox does not free up unused disk space. To automatically shrink the vdi disk image the discard option must be enabled:

  VBoxManage storageattach <VM name> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on
  

• title: KVM (virt-manager) content: |

  1. Create a new virtual machine in virt-manager
  2. Select "Import existing disk image", provide the path to the QCOW2 image above
  3. Choose "Generic Default" for the operating system
  4. Check the box for "Customize configuration before install"
  5. Select your bridge under "Network Selection"
  6. Under customization select "Overview" -> "Firmware" -> "UEFI x86_64: ...". Make sure to select a non-secureboot version of OVMF (does not contain the word secure, secboot, etc.), e.g., /usr/share/edk2/ovmf/OVMF_CODE.fd.
  7. Click "Add Hardware" (bottom left), and select "Channel"
  8. Select device type: "unix"
  9. Select name: "org.qemu.guest_agent.0"
  10. Finally select "Begin Installation" (upper left corner)

• title: KVM (virt-install) content: |

  virt-install --name hass --description "Home Assistant OS" --os-variant=generic --ram=2048 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=sata --graphics none --boot uefi
  

  If you have a USB dongle to attach, you need to add the option `--hostdev busID.deviceId`. You can discover these IDs via the `lsusb` command. As example, if `lsusb` output is:

     Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
     Bus 003 Device 004: ID 30c9:0052 Luxvisions Innotech Limited Integrated RGB Camera
     Bus 003 Device 003: ID 1a86:55d4 QinHeng Electronics SONOFF Zigbee 3.0 USB Dongle Plus V2
     Bus 003 Device 002: ID 06cb:00fc Synaptics, Inc. 
     Bus 003 Device 005: ID 8087:0033 Intel Corp. 
     Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
     Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
     Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
  

  You can recognize the Sonoff dongle at Bus 003 Device 003. So the command to install the VM will become:

  virt-install --name hass --description "Home Assistant OS" --os-variant=generic --ram=2048 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=sata --graphics none --boot uefi --hostdev 003.003
  

  Note that this configuration (bus 003, device 003) is just an example, your dongle could be on another bus and/or with another device ID. Please check the correct IDs of your USB dongle with lsusb.

{% if page.installation_type == 'windows' or page.installation_type == 'linux' %}

• title: Vmware Workstation content: |

  1. Create a new virtual machine
  2. Select “Custom”, make it compatible with the default of Workstation and ESX
  3. Choose “I will install the operating system later”, select “Linux” -> “Other Linux 5.x or later kernel 64-bit”
  4. Select “Use Bridged Networking”
  5. Select “Use an existing virtual disk” and select the VMDK file above,

  After creation of VM go to “Settings” and “Options” then “Advanced” and select “Firmware type” to “UEFI”.

{% elsif page.installation_type == 'alternative' %}

• title: VMware ESXi/vSphere content: | Use the “E1001” or “E1001E” virtual network adapter. There are confirmed mDNS/Multicast discovery issues when using VMware’s “VMXnet3” virtual network adapter. {% endif %} {% if page.installation_type == 'windows' %}

• title: Hyper-V content: |

  Hyper-V does not have USB support
  1. Create a new virtual machine
  2. Select “Generation 2”
  3. Select “Connection -> “Your Virtual Switch that is bridged”
  4. Select “Use an existing virtual hard disk” and select the VHDX file from above

  After creation go to “Settings” -> “Security” and deselect “Enable Secure Boot”. {% endif %}

{% endtabbed_block %}

Start up your Virtual Machine

1. Start the Virtual Machine
2. Observe the boot process of Home Assistant Operating System
3. Once completed you will be able to reach Home Assistant on homeassistant.local:8123. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at homeassistant:8123 or http://X.X.X.X:8123 (replace X.X.X.X with your {{site.installation.types[page.installation_type].board}}’s IP address).

{% endif %}

With the Home Assistant Operating System installed and accessible you can continue with onboarding.

{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %}