Installing Home Assistant

Running Home Assistant in a VM: Proxmox, Hyper-V and VirtualBox

Install Home Assistant OS in a VM on Proxmox, Hyper-V or VirtualBox, with the right disk image, UEFI setup, bridged networking and USB dongle notes.

On this page
  1. Should you run Home Assistant in a VM?
  2. What every VM setup needs
  3. Proxmox VE
  4. Hyper-V on Windows
  5. VirtualBox
  6. Zigbee, Z-Wave and Thread radios in a VM
  7. How to set up Home Assistant to work remotely
  8. Snapshots and backups
  9. Common mistakes

Should you run Home Assistant in a VM?

Running Home Assistant OS in a virtual machine works well if you already have a hypervisor and want other services on the same machine. Home Assistant’s own guidance is that if you aren’t familiar with virtual machines, you should install Home Assistant OS directly on supported hardware instead.

A VM is a poor fit for a desktop Windows PC that you restart for updates. Each host restart stops your automations, so use a machine that stays on for the VM.

What every VM setup needs

  • Resources. At least 2 vCPUs and 2 GB of RAM. 4 GB of RAM is more comfortable with add-ons. The default disk is 32 GB.
  • Firmware. UEFI, with Secure Boot turned off. The image won’t boot under legacy BIOS.
  • Networking. A bridged or external network, so Home Assistant gets its own IP address on your LAN. NAT networking breaks device discovery and inbound access.

Which Home Assistant image do you need?

Download the HAOS image that matches your hypervisor:

Hypervisor Image format
Proxmox or KVM .qcow2
Hyper-V .vhdx
VirtualBox .vdi
VMware ESXi or vSphere .ova

Get the file from the Home Assistant installation page. Extract it if it’s compressed.

Proxmox VE

You have two options.

Option 1: community helper script. The community-scripts project publishes a Home Assistant OS VM script that you run from the Proxmox node’s Shell. It’s maintained outside the Home Assistant project and runs as root on your Proxmox host, so read it before you run it. The script creates the VM for you with defaults, typically 4 GB of RAM, 32 GB of storage and 2 vCPUs.

Option 2: import the disk manually.

  1. Copy the KVM/Proxmox .qcow2.xz link from the Home Assistant installation page.
  2. In the Proxmox Shell, download the file with wget <link>, then extract it with unxz haos_ova-<version>.qcow2.xz.
  3. Click Create VM. Set a name. Under OS, choose Do not use any media. Under System, set Machine to q35, BIOS to OVMF (UEFI), and tick QEMU Guest Agent. Add an EFI disk.
  4. On the Disks step, delete the default disk.
  5. Set the CPU to 2 cores and the memory to 4096 MB (4 GB) or more.
  6. Import the extracted image from the Shell:
qm importdisk <VM-ID> haos_ova-<version>.qcow2 <storage>
  1. In the VM’s Hardware tab, attach the unused disk. In Options, set it first in the boot order.
  2. Start the VM. Open the Console to see its IP address, then go to http://<IP-address>:8123.

To pass a USB radio into the VM, add it under the VM’s Hardware tab by vendor and device ID. That setting survives port changes, unlike a port-based setting.

Hyper-V on Windows

Hyper-V comes with Windows Pro and Enterprise, but not Windows Home.

How to enable Hyper-V in Windows

Open Turn Windows features on or off, tick Hyper-V, and restart when prompted. Then create the VM.

  1. Download the Hyper-V .vhdx image and extract it.
  2. In Hyper-V Manager, create an External virtual switch linked to your Ethernet adapter, or to your Wi-Fi adapter if you have no wired option.
  3. Create a Generation 2 VM with at least 2 GB of memory and 2 virtual processors.
  4. Select Use an existing virtual hard disk, then choose the .vhdx file.
  5. In the VM’s Settings > Security, clear Enable Secure Boot.
  6. Connect the VM to the external switch, start it, and open http://homeassistant.local:8123 or the VM’s IP address.

Is Hyper-V different from VMware?

Yes. Hyper-V is Microsoft’s hypervisor, built into Windows Pro and Enterprise. VMware is a separate family of products, with its own tools and its own Home Assistant image (.ova). Either can run Home Assistant if the network is bridged and UEFI is set up. This guide sticks to Hyper-V.

Hyper-V has no native USB passthrough. Use a network-attached Zigbee or Z-Wave coordinator, or a USB-over-IP tool, to connect a radio.

VirtualBox

VirtualBox is useful for testing. It’s less suited to a 24/7 server because the host computer must stay on.

  1. Install VirtualBox and extract the .vdi image.
  2. Click New. Name the VM Home Assistant. Set Type to Linux and Version to Oracle Linux (64-bit). On Apple silicon, choose Oracle Linux (ARM 64-bit). On the disk step, choose Do not add a virtual hard disk.
  3. Set at least 2048 MB of memory and 2 CPUs. Under System, tick Enable EFI.
  4. Open Settings > Storage, and add the .vdi file to the SATA controller.
  5. Under Network, set Attached to to Bridged Adapter, and choose the adapter you use for internet access.
  6. Start the VM and open http://homeassistant.local:8123.

USB passthrough in VirtualBox needs the Oracle VM VirtualBox Extension Pack.

Zigbee, Z-Wave and Thread radios in a VM

A USB radio needs passthrough to reach the VM:

  • Proxmox: pass the device by vendor and device ID.
  • VirtualBox: install the Extension Pack, which enables USB 2.0 and 3.0 passthrough.
  • Hyper-V: no native passthrough. Use a network-attached coordinator or USB-over-IP.

If you’re buying a radio for a VM, a network-attached coordinator avoids passthrough entirely.

How to set up Home Assistant to work remotely

Use one of three options: Home Assistant Cloud, a paid subscription; a VPN such as Tailscale, which keeps your Home Assistant private; or a Cloudflare Tunnel. Don’t forward port 8123 to the internet without TLS and strong authentication.

Snapshots and backups

Snapshots before a major update give you a quick rollback. They don’t replace Home Assistant backups. Keep both, and store Home Assistant backups off the VM host.

Common mistakes

  • NAT networking. Device discovery and inbound access break. Use bridged or external networking.
  • Legacy BIOS. The Home Assistant VM images need UEFI.
  • VirtualBox on a laptop for 24/7 use. The host has to stay on, so use it for testing.
  • Running community scripts without reading them. Read the script first, because it runs with full control of the host.

If your host is a NAS rather than a hypervisor, see running Home Assistant on a NAS or Docker. For other ways to install, see how to install Home Assistant.

The complete guide to installing home assistant

How to Install Home Assistant: Every Self-Hosted Method Compared
Read the guide

Keep exploring

Guides from other topics

All topics →