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 or Fast Alerts (US) to find webshops 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 generic x86 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 write the HAOS (Home Assistant OS) disk image directly to your boot media, and configure your x86 to use UEFI boot mode when booting from this media.

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 systems. 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 the changes and exit.

• The BIOS configuration is complete.

As a next step, we need to write the Home Assistant Operating System image to the target boot medium. The HAOS has no integrated installer. This means the Operating System is not copied automatically to the internal disk.

• The "boot medium" is the medium your x86-64 hardware will boot from when it is running Home Assistant.
• Typically, an internal medium is used for the x86-64 hardware. Examples of internal media are S-ATA hard disk, S-ATA SSD, M.2 SSD, or a non-removable eMMC.
• Alternatively, an external medium can be used to boot HAOS such as a USB SDD (not recommended).

To install the HAOS internally on your x86-64 hardware, there are 2 methods:

1. Copying the HAOS disk image from your Desktop computer onto your boot medium (e.g. by using a USB to S-ATA adapter). This is not an option for a non-removable eMMC on your x86-64 hardware, of course. To use this method, follow the steps described in the procedure below: Write the image to your boot media.
2. Copying a live operating system (e.g. Ubuntu) onto a USB device. Then, insert this USB device into your x86-64 hardware and start the Ubuntu.

• To use this method, follow the instructions of your Live distribution (e.g., this Ubuntu guide). Once you booted the live operating system, follow the steps described in the procedure below: Write the image to your boot media.

{% endif %}

Write the image to your boot media

1. Attach the Home Assistant boot media ({{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. Get the URL for your {{site.installation.types[page.installation_type].board}}: {% 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 your {{site.installation.types[page.installation_type].board}} into Balena Etcher and click "OK"
2. Balena Etcher will now download the image, when that is done click "Select target"
3. Select the {{site.installation.types[page.installation_type].installation_media}} you want to use for your {{site.installation.types[page.installation_type].board}}
4. Click on "Flash!" to start writing the image
5. When Balena Etcher is finished writing the image you will get this confirmation

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

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

1. If you used your desktop system to write the HAOS your boot media, install the boot media ({{site.installation.types[page.installation_type].installation_media}}) in the generic-x86-64 system.

• If you used a live operating system (e.g. Ubuntu), shut down the live operating system and make sure to remove the USB flash drive you used for the live system.

2. Make sure an Ethernet cable is plugged in for network.

3. Power the system on.

   • Wait for the Home Assistant welcome banner to show up in the console of the generic-x86-64 system. {% else %}

4. Insert the boot media ({{site.installation.types[page.installation_type].installation_media}}) you just created.

5. Attach an Ethernet cable for network.

6. Attach the power cable. {% endif %}

7. In the browser of your Desktop system, within a few minutes you will be able to reach your new 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).

{% 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:

• 2GB RAM
• 32GB 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
  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 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: …”
  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 Instalation" (upper left corner)

{% 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/" %}