Alternative
Install Home Assistant Operating System
Download the appropriate image
-
VirtualBox
(.vdi) -
KVM/Proxmox
(.qcow2) -
VMware ESXi/vSphere
(.ova)
After downloading, decompress the image. If the image comes in a ZIP file, for example, unzip it.
Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines, install Home Assistant OS directly on a Home Assistant Yellow, 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
- Create a new virtual machine.
- Select type Linux and version Linux 2.6 / 3.x / 4.x (64-bit).
- Under Hardware, select the amount of memory and number of CPUs. Then, select Enable EFI.
- Make sure EFI is enabled. If EFI is not enabled, HAOS won’t boot.
- Under Hard Disk, select Use an existing virtual hard disk file, select the unzipped VDI file from above.
- 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. - Then go to Audio and choose Intel HD Audio as audio controller.
discard
option must
be enabled using your host machine’s terminal:
VBoxManage storageattach <VM name> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on
More details can be found about the command can be found here
- Download the .qcow2 image above and decompress it. (Extract all in Windows)
- Store the image in the isos share on your server.
- Make sure under Settings > VM manager, Enable VMs is enabled.
- Create a new virtual machine: VMS > Add VM.
- Select type Linux and give the VM a name and a description.
- Select the CPU cores you want to let the VM use and give it some memory.
- Under Primary vDisk Location, select Manual and then select the qcow2 image.
- Select your keyboard language under VM Console Keyboard.
- Select br0 under Network Source.
- Select virtio under Network model.
- Select any USB-devices that you want to pass through to Home Assistant, such as Zigbee- or Z-Wave controllers.
- Deselect Start VM after creation.
- Select Create.
- Select the name of your new VM and select the capacity number for your disk. Here, you can expand the disk to whatever your needs are. The default is 32 GB.
- Select the icon of your new VM and select start with console (VNC).
- Create a new virtual machine in
virt-manager
. - Select Import existing disk image, provide the path to the QCOW2 image above.
- Choose Generic Default for the operating system.
- Check the box for Customize configuration before install.
- Under Network Selection, select your bridge.
- 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
. - Click Add Hardware (bottom left), and select Channel.
- Select device type: unix.
- Select name: org.qemu.guest_agent.0.
- Finally, select Begin Installation (upper left corner).
virt-install --name haos --description "Home Assistant OS" --os-variant=generic --ram=4096 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=scsi --controller type=scsi,model=virtio-scsi --import --graphics none --boot uefi
--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 haos --description "Home Assistant OS" --os-variant=generic --ram=4096 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=scsi --controller type=scsi,model=virtio-scsi --import --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
.
Use the “E1001” or “E1001E” virtual network adapter. There are confirmed mDNS/Multicast discovery issues when using VMware’s “VMXnet3” virtual network adapter.
Start up your virtual machine
- Start the virtual machine.
- Observe the boot process of the Home Assistant Operating System.
- 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 ’s IP address).
Help us improve Home Assistant
Have you just installed Home Assistant? The Home Assistant team is looking to talk to you to understand how the installation went.
Help nowWith the Home Assistant Operating System installed and accessible, you can continue with onboarding.
Install Home Assistant Container
Synology NAS
Synology with DSM now supports Docker, allowing you to install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.synology.com/en-us/dsm/packages/Docker
The steps would be:
- Install Docker “Container Manager” package on your Synology NAS
- Launch Container Manager-app and move to “Registry”-section
- Find “homeassistant/home-assistant” within registry and click on “Download”. Choose the “stable” tag.
- Wait for some time until your NAS has pulled the image
- Move to the “Image”-section of the “Container Manager”-app
- Click on “Launch”
- Within “Network” select “Use same network as Docker Host” and click Next
- Choose a container-name you want (e.g., “homeassistant”)
- Set “Enable auto-restart” if you like
- Click on “Advanced Settings”. To ensure that Home Assistant displays the correct timezone go to the “Environment” tab and click the plus sign then add
variable
=TZ
&value
=Europe/London
choosing your correct timezone. Click Save to exit Advanced Settings. - Click Next
- Within “Volume Settings” click on “Add Folder” and choose either an existing folder or add a new folder (e.g. in “docker” shared folder, add new folder named “homeassistant” and then within that new folder add another new folder “config”), then click Select. Then edit the “mount path” to be “/config”. This configures where Home Assistant will store configs and logs.
- Ensure “Run this container after the wizard is finished” is checked and click Done
- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example
http://192.168.1.10:8123
)
If you are using the built-in firewall, you must also add the port 8123 to allowed list. This can be found in “Control Panel -> Security” and then the Firewall tab. Click “Edit Rules” besides the Firewall Profile dropdown box. Create a new rule and select “Custom” for Ports and add 8123. Edit Source IP if you like or leave it at default “All”. Action should stay at “Allow”.
To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal access to your Synology NAS:
https://www.synology.com/en-global/knowledgebase/DSM/help/DSM/AdminCenter/system_terminal
Adjust the following Terminal command as follows :
- Replace
/PATH_TO_YOUR_CONFIG
points at the folder where you want to store your configuration - make sure that you keep the:/config
part - Replace
/PATH_TO_YOUR_USB_STICK
matches the path for your USB stick (e.g.,/dev/ttyACM0
for most Synology users) - Replace “Australia/Melbourne” with your timezone
Run it in Terminal.
sudo docker run --restart always -d --name homeassistant -v /PATH_TO_YOUR_CONFIG:/config --device=/PATH_TO_YOUR_USB_STICK -e TZ=Australia/Melbourne --net=host ghcr.io/home-assistant/home-assistant:stable
Complete the remainder of the Z-Wave configuration by following the instructions here.
Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following:
- Go to the “Container Manager”-app and move to “Image”-section
- Find “homeassistant/home-assistant” within Image and click on “Update”.
- Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar)
- Move to “Container”-section
- Stop your container if it’s running
- Right-click on it and select “Action”->“Reset”. You won’t lose any data, as all files are stored in your configuration-directory
- Start the container again - it will then boot up with the new Home Assistant image
Remark: to restart your Home Assistant within Synology NAS, you just have to do the following:
- Go to the “Container Manager”-app and move to “Container”-section
- Right-click on it and select “Action”->“Restart”.
If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided here
QNAP NAS
QNAP with QTS supports Docker, allowing you to install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.qnap.com/solution/container_station/en/index.php
The steps would be:
- Install “Container Station” package on your Qnap NAS
- Launch Container Station and move to “Create Container”-section
- Search image “homeassistant/home-assistant” with Docker Hub and click on “Install” Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is “homeassistant/armhf-homeassistant”
- Choose “stable” version and click next
- Choose a container-name you want (e.g., “homeassistant”)
- Click on “Advanced Settings”
- Within “Shared Folders” click on “Volume from host” > “Add” and choose either an existing folder or add a new folder. The “mount point has to be
/config
, so that Home Assistant will use it for the configuration and logs. - Within “Network” and select Network Mode to “Host”
- To ensure that Home Assistant displays the correct timezone go to the “Environment” tab and click the plus sign then add
variable
=TZ
&value
=Europe/London
choosing your correct timezone - Click on “Create”
- Wait for some time until your NAS has created the container
- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example
http://192.xxx.xxx.xxx:8123
)
Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don’t remove “config” folder).
Once the Home Assistant Container is running Home Assistant should be accessible using http://<host>:8123
(replace
Restart Home Assistant
If you change the configuration, you have to restart the server. To do that you have 3 options.
- In your Home Assistant UI, go to the Settings > System and click the Restart button.
- You can go to the Developer Tools > Actions, select
homeassistant.restart
and select Perform action. - Restart it from a terminal.
docker restart homeassistant
docker compose restart
Docker compose
As the Docker command becomes more complex, switching to docker compose
can be preferable and support automatically restarting on failure or system restart. Create a compose.yml
file:
services:
homeassistant:
container_name: homeassistant
image: "ghcr.io/home-assistant/home-assistant:stable"
volumes:
- /PATH_TO_YOUR_CONFIG:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
restart: unless-stopped
privileged: true
network_mode: host
Start it by running:
docker compose up -d
Once the Home Assistant Container is running, Home Assistant should be accessible using http://<host>:8123
(replace
Exposing devices
In order to use Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the /dev/tty*
file, then add the device mapping to your container instructions:
docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ...
services:
homeassistant:
...
devices:
- /dev/ttyUSB0:/dev/ttyUSB0
Optimizations
The Home Assistant Container is using an alternative memory allocation library jemalloc
As the jemalloc configuration used can cause issues on certain hardware featuring a page size larger than 4K (like some specific ARM64-based SoCs), it can be disabled by passing the environment variable DISABLE_JEMALLOC
with any value, for example:
docker run ... -e "DISABLE_JEMALLOC=true" ...
services:
homeassistant:
...
environment:
DISABLE_JEMALLOC: true
The error message <jemalloc>: Unsupported system page size
is one known indicator.
Community provided guides
Additional installation guides can be found on our Community Forum.
These Community Guides are provided as-is. Some of these install methods are more limited than the methods above. Some integrations may not work due to limitations of the platform.