If you've been poking around the self-hosting and smart home world for more than a week, you've heard of Home Assistant. It's the open-source platform that lets you control lights, thermostats, cameras, and just about any smart device from one dashboard, without shipping your data to a company's cloud server. And if you're already running Proxmox VE for your homelab, putting Home Assistant in its own virtual machine is one of the more satisfying weekend projects you can take on.
This guide walks through installing Home Assistant OS (HAOS) — the dedicated operating system version, not the Docker container or the Home Assistant Core Python install — as a VM inside Proxmox VE 9.x. You'll download the official image, import it by hand using the Proxmox shell, and get it booted with the right firmware settings so you don't hit the two or three gotchas that trip up almost everyone the first time.
What You Will Learn
By the end of this tutorial you'll know how to:
- Download and extract the official Home Assistant OS disk image
- Create a Proxmox VE virtual machine with the correct firmware and machine type for HAOS
- Import the qcow2 disk image using
qm importdiskinstead of the GUI upload wizard - Attach the imported disk, add an EFI disk, and fix the boot order
- Avoid the secure boot and disk size mistakes that cause a black screen or a boot loop
- Find your new Home Assistant instance on the network and finish onboarding
What Is Home Assistant OS?
Home Assistant OS is a minimal, purpose-built Linux operating system whose only job is running Home Assistant. Instead of installing Debian or Ubuntu and then setting up Docker, Python, and a dozen dependencies yourself, HAOS gives you a locked-down appliance image: you boot it, open a web browser, and start adding devices.
It ships as a qcow2 file, which is a disk image format used by QEMU (the virtualization engine underneath Proxmox VE). Think of it as a virtual hard drive in a box — you don't install an operating system onto a blank disk, you just hand the whole pre-built disk to a new VM and boot it.
HAOS also uses OVMF, which is the UEFI firmware Proxmox VMs use instead of old-style BIOS. UEFI is the modern replacement for the BIOS boot process most of us grew up with, and HAOS specifically requires it — it won't boot with the legacy "SeaBIOS" option that Proxmox uses by default for new VMs.
Why Would You Use It?
You could run Home Assistant as a container on a Synology, a Raspberry Pi, or an old laptop. Plenty of people do. But running it as a VM inside Proxmox gets you a few things those setups don't:
- Snapshots. Before you update Home Assistant or install a risky add-on, take a snapshot. If something breaks, you're back to a working state in under a minute.
- Backups that live with the rest of your infrastructure. If you're already backing up other VMs with vzdump or Proxmox Backup Server, Home Assistant rides along automatically.
- Resource isolation. HAOS gets its own CPU and memory allocation, so a misbehaving add-on can't starve your other services — or the other way around.
- Easy hardware upgrades. Migrating to new hardware later is a live migration or a backup-and-restore, not a fresh SD card flash.
Honestly, if you're only running one or two smart home integrations, a Raspberry Pi is fine and probably simpler. Where the Proxmox route pays off is once you start adding Zigbee, a few dozen automations, and add-ons like Node-RED or ESPHome — at that point you'll want the snapshot safety net.
Prerequisites
Before you start, make sure you have:
- A working Proxmox VE 9.x host (this also works fine on 8.x, the process hasn't changed)
- At least 4 GB of RAM and 32 GB of free storage to spare for the VM
- Shell or SSH access to your Proxmox node — Datacenter > your node > Shell in the web UI works fine
- A network connection for the Proxmox host so it can download the image
- About 15 minutes, most of which is waiting for a download
You don't need to know anything about Home Assistant itself yet — the onboarding wizard handles device discovery and account setup after the VM is running.
Step-by-Step Tutorial
Step 1: Download the Home Assistant OS image
Open a shell on your Proxmox node and download the current qcow2 image from the official Home Assistant releases. Check the operating-system releases page for the newest version number first — at the time of writing the current release is 18.1, but this number changes every few months.
cd /var/lib/vz/template/iso
wget https://github.com/home-assistant/operating-system/releases/download/18.1/haos_ova-18.1.qcow2.xzThat puts the file in Proxmox's own ISO storage directory, which is a convenient place to keep it, though it isn't required — you can download it anywhere with enough free space.
Step 2: Extract the image
The download is compressed with xz, so unpack it before Proxmox can use it:
unxz haos_ova-18.1.qcow2.xzYou'll be left with a plain haos_ova-18.1.qcow2 file, roughly 6 GB. Extraction takes a minute or two depending on your storage speed.
Step 3: Create the VM shell
In the Proxmox web interface, click Create VM in the top right. Fill in the wizard as follows, and pay attention to the two settings that differ from a normal Windows or Linux VM:
- General: pick a VM ID (note it down — you'll need it in Step 4) and a name like
homeassistant. - OS: select Do not use any media. You're not installing from an ISO — the disk image already has an OS on it.
- System: set BIOS to OVMF (UEFI) and Machine to q35. Leave Add EFI Disk checked, but uncheck Pre-Enroll keys — this is the setting that prevents a secure boot failure later.
- Disks: remove the default disk entirely, or just leave it as a small placeholder — you'll delete it after importing the real one. Don't spend time sizing it.
- CPU: 2 cores is the documented minimum; 2–4 is comfortable for most homes.
- Memory: 4096 MB. HAOS will run on 2 GB, but add-ons like the Supervisor's own database and any Zigbee integration add up fast.
- Network: leave the default VirtIO model on
vmbr0(or whichever bridge your other VMs use).
Click through to Finish but don't start the VM yet.
Step 4: Import the disk
Back in the shell, run qm importdisk, pointing it at the file you extracted and the VM ID you just created. Replace 100 with your actual VM ID and local-lvm with whatever storage you want the disk to live on:
qm importdisk 100 /var/lib/vz/template/iso/haos_ova-18.1.qcow2 local-lvmThis takes the qcow2 file and converts it into a disk attached to VM 100, sitting in an "unused" state. It doesn't attach it to anything yet — that's the next step.
Step 5: Attach the imported disk
Go to your VM in the web UI, click Hardware, and you'll see a new line called Unused Disk 0. Double-click it, and in the dialog that opens, make sure the bus is set to SCSI with the VirtIO SCSI single controller, then click Add.
If you left a placeholder disk from Step 3, select it and click Detach, then Remove — you don't want two disks competing to be the boot device.
Step 6: Fix the boot order
Click Options in the VM's left-hand menu, then Boot Order. Enable the SCSI disk you just attached and drag it to the top of the list. Disable anything else in the list — a leftover CD-ROM entry is the usual culprit for a VM that just sits at a blank EFI shell prompt instead of booting.
Step 7: Resize the disk (optional but recommended)
The imported disk matches the size of the original image, which is small. HAOS expands its data partition automatically on first boot, but only up to whatever size the underlying virtual disk actually is. Give it more room now, before you boot it the first time:
qm resize 100 scsi0 32G32 GB is plenty for years of history and a handful of add-ons. You can always grow it again later the same way.
Step 8: Start the VM and watch the console
Click Start, then open the Console tab. You'll see a fairly plain boot log — HAOS doesn't have a flashy splash screen. Give it three to five minutes on the first boot. It's expanding partitions and starting the Supervisor in the background even after the login prompt appears, so don't panic if the web interface isn't reachable immediately.
Step 9: Find it and finish onboarding
Once it's settled, open a browser on a machine on the same network and go to:
http://homeassistant.local:8123If mDNS discovery doesn't resolve that hostname on your network, check your router's DHCP client list for a device named homeassistant and use its IP address instead, like http://192.168.1.50:8123. From there, the Home Assistant onboarding wizard takes over — create your account, set your location, and let it scan for devices.
Commands Explained
| Command | What it does |
|---|---|
wget <url> | Downloads the compressed HAOS image directly to your Proxmox host from GitHub. |
unxz <file>.xz | Decompresses the .xz archive, leaving the raw .qcow2 disk image behind. |
qm importdisk <vmid> <file> <storage> | Converts an existing disk image into a disk attached to a specific VM ID, placed on the storage you name. It lands as an unused disk until you attach it in the Hardware tab. |
qm resize <vmid> <disk> <size> | Grows a VM's virtual disk to the new size you specify. It only grows — you can't shrink a disk this way. |
Common Errors
"No bootable device found" or a blank UEFI shell. Almost always the boot order. Go back to Options > Boot Order and confirm the SCSI disk is enabled and at the top, with everything else disabled.
VM boots straight to a "Secure Boot Violation" screen. HAOS isn't signed for secure boot. If you forgot to uncheck Pre-Enroll keys when creating the EFI disk, remove the EFI disk and re-add it with that box unchecked.
homeassistant.local doesn't resolve. mDNS depends on your router and client OS supporting it — some routers with strict AP isolation or VLANs block it outright. Falling back to the IP address from your DHCP lease list always works.
Import finishes but nothing shows up in Hardware. Double check you used the VM ID from Step 3, not a random number. qm importdisk silently fails to attach anywhere if you point it at a VM ID that doesn't exist yet — create the VM first.
Troubleshooting
If the VM starts but the console shows kernel panics or repeated reboots, the most common cause is a corrupted download — the qcow2 file got cut off mid-transfer. Check the file size against the release page, or re-download and compare with sha256sum if the release includes a checksum file.
If onboarding loads but device discovery finds nothing, that's usually a networking issue rather than a Home Assistant issue. Confirm the VM's network device is on a bridge that actually reaches your LAN — vmbr0 with no VLAN tag is the safe default for a first install. If your smart home devices sit on a separate VLAN, HAOS won't see them until you either tag the VM's interface or route between VLANs.
For anything else, the Supervisor logs are more useful than the console. Once you're through onboarding, go to Settings > System > Logs inside Home Assistant itself rather than trying to read the Proxmox console output.
Best Practices
- Take a snapshot before every Home Assistant Core or Supervisor update. Updates are usually smooth, but add-on compatibility breaks occasionally, and a snapshot turns a bad update into a two-minute rollback.
- Reserve a static DHCP lease for the VM in your router rather than trying to configure a static IP inside HAOS. It's simpler, and it survives VM recreation.
- Set the VM to start automatically on host boot (Options > Start at boot) so Home Assistant comes back up on its own after a Proxmox reboot or power cut.
- Keep the extracted qcow2 file around for a while after a successful install — if an update goes sideways and a snapshot isn't available, having the original image saves a re-download.
- Don't install the QEMU Guest Agent inside HAOS. It's a locked-down appliance OS without a general package manager, and Proxmox works fine without it here — you just won't see the VM's IP address in the Summary tab.
Frequently Asked Questions
Can I use the Proxmox GUI's built-in ISO upload instead of the shell?
No — the GUI's upload feature is for ISO installer images, not pre-built qcow2 disks. You need qm importdisk or the newer GUI "Import Disk Image" option under a storage's content view, if your Proxmox version has it.
How much RAM does Home Assistant OS actually need?
The documented minimum is 2 GB, but 4 GB is a more realistic number once you add a few integrations and the built-in database grows. If you're running Zigbee2MQTT or a lot of history graphs, consider 6 GB.
Why q35 instead of the default i440fx machine type?
q35 is a newer virtual chipset with native PCIe support, and it's what HAOS expects paired with OVMF. Using i440fx with UEFI firmware can cause boot instability on some Proxmox versions.
Can I passthrough a USB Zigbee stick to this VM?
Yes. Add it under Hardware > Add > USB Device once the VM exists. Passing through the specific device (not just the USB controller) lets you unplug and replug it without reconfiguring the VM.
Do I need to install the QEMU Guest Agent?
No, and you can't easily — HAOS doesn't expose a normal package manager for host-level tools. Skip it.
Conclusion
The whole process boils down to five things: download the image, extract it, create a VM with OVMF and q35, import the disk with qm importdisk, and fix the boot order. Once you've done it once, it takes less time than watching the download finish. The only part worth double-checking twice is the EFI disk's secure boot setting — get that wrong and you'll spend ten minutes staring at a screen that never quite explains why it won't boot.
From here, the real work is inside Home Assistant itself: adding integrations, wiring up automations, and slowly replacing whatever app your smart thermostat wants you to use instead.