Installing Home Assistant OS (HAOS) in KVM on Raspberry Pi 5

October 12, 2025

Running Home Assistant OS (HAOS) natively on a Raspberry Pi is common, but virtualizing it in KVM unlocks flexibility for home lab setups or multi-purpose Pi 5 systems. This guide shows you, step-by-step, how to set up HAOS in a KVM virtual machine on your Raspberry Pi 5 (64-bit).

Technology Stack Components:

Hardware Layer: Raspberry Pi 5 with ARM64 architecture and hardware virtualization extensions
Host OS: Raspberry Pi OS (Debian-based) providing the foundation
Hypervisor: QEMU/KVM for hardware-accelerated virtualization
Management Layer:
- libvirt daemon for VM lifecycle management and networking
- Cockpit web UI (with cockpit-machines) for graphical VM administration
Guest OS: Home Assistant Operating System running as an isolated virtual machine
Network Bridge: Direct ethernet connection allowing VM to appear as a native network device

Prerequisites

Raspberry Pi 5 running Raspberry Pi OS 64-bit (Bookworm or newer recommended)
Sufficient RAM (at least 4GB, 8GB strongly recommended)
Hardware virtualization support enabled (available by default on RPi5)
Basic Linux terminal skills

Step 1: Install Required Packages

First, install the packages for libvirt, KVM, bridge-utils, and the virt-install utility:

sudo apt install -y libvirt-daemon-system libvirt-clients bridge-utils virtinst

Add and configure the appropriate system user:

sudo groupadd --system libvirt-qemu
sudo useradd --system -g libvirt-qemu -G kvm -s /sbin/nologin -d / -c "Libvirt QEMU user" libvirt-qemu
sudo systemctl restart libvirtd
sudo usermod -aG libvirt,kvm \$(whoami)
newgrp libvirt

Check that the libvirt service is running:

systemctl status libvirtd

Optionally, install Cockpit with the virtualization plugin for easy web management:

sudo apt install -y cockpit cockpit-machines
sudo systemctl status cockpit.socket
# Access in browser: https://<rpi5-ip>:9090/

Step 2: Configure the Default Network

Start and enable the default libvirt network (required for VM networking):

sudo virsh net-start default
sudo virsh net-autostart default

Step 3: Download HAOS QCOW2 Image

Get the latest HAOS image for aarch64 (ARM 64-bit, generic):

wget https://github.com/home-assistant/operating-system/releases/download/16.2/haos_generic-aarch64-16.2.qcow2.xz
unxz haos_generic-aarch64-16.2.qcow2.xz

(Optional) Adjust permissions if needed:

sudo chmod o+x /home/youruser /home/youruser/haos

Step 4: Expand the Disk Image

Increase the QCOW2 image size for more storage (optional but recommended):

sudo qemu-img resize haos_generic-aarch64-16.2.qcow2 +32G

Step 5: Create and Run the Virtual Machine

Here’s the key step: using virt-install to create and launch the HAOS VM.

sudo virt-install \
--name haos \
--description "Home Assistant OS" \
--os-variant=generic \
--ram=6144 \
--vcpus=2 \
--disk haos_generic-aarch64-16.2.qcow2,bus=scsi \
--controller type=scsi,model=virtio-scsi \
--import \
--graphics none \
--boot uefi \
--noautoconsole \
--network network=default,model=virtio,mac=52:54:00:fa:72:01 \
--network direct,source=eth0,source_mode=bridge,model=virtio,mac=52:54:00:4a:19:02 \
--boot uefi,firmware.feature0.name=enrolled-keys,firmware.feature0.enabled=no,firmware.feature1.name=secure-boot,firmware.feature1.enabled=no

Parameter Explanation:

--name haos: Name of the VM
--description: Description in the VM manager
--os-variant=generic: OS type (generic for best ARM64 compatibility)
--ram=6144: Allocates 6GB RAM (adjust as needed)
--vcpus=2: 2 virtual CPUs
--disk ...: Attach the downloaded QCOW2 HAOS disk image with SCSI bus for performance
--controller type=scsi,model=virtio-scsi: Use the VirtIO SCSI controller for disk I/O efficiency
--import: Import an existing disk image (don’t use an install ISO)
--graphics none: Headless (no graphical console)
--boot uefi: Boot with UEFI firmware (required for HAOS)
--noautoconsole: Do not auto-connect to console after start
--network network=default,...: Connects VM to default NAT network (Internet access)
--network direct,source=eth0,source_mode=bridge,...: Adds a bridged interface for access on the local LAN
--boot uefi,...secure-boot disabled: Ensures UEFI starts without secure boot features (needed for HAOS images)

Note: You may need to tweak the MAC addresses or network interface (eth0) based on your hardware setup.

Step 6: Enable Autostart for HAOS VM

Make sure the HAOS VM starts automatically on boot:

sudo virsh autostart haos

Cockpit showing VM management on Raspberry Pi 5:

Step 7: Accessing Home Assistant on Your Network

Your Home Assistant OS virtual machine is now running! From any other device on your LAN (desktop, laptop, smartphone, etc.), you can access the Home Assistant interface by navigating to:

http://homeassistant.local:8123

Accessing from the Raspberry Pi 5 Host

Important Note: If you are trying to access Home Assistant directly from the Raspberry Pi 5 host (the machine running the VM), you may encounter connectivity issues. This is because the VM is using a direct bridge connection to eth0, which puts it on the same physical network segment as the host.

In this configuration, the host often cannot reach the VM’s IP address through the normal routing path, even though other devices on the LAN can access it without issues.

Workaround: If you need to access Home Assistant from the Pi 5 host itself, you can:

Use SSH tunneling: ssh -L 8123:VM_IP:8123 user@VM_IP

Access via the default NAT network (virbr0) if you configured a second network interface

Use another device on your network to manage Home Assistant

For most users, accessing Home Assistant from other devices on the network works perfectly with the bridged setup, providing optimal performance and direct LAN connectivity.

When you access Home Assistant from your browser, you’ll be greeted by the onboarding screen:

Follow the guided setup to create your account, configure core integrations, and begin building your smart home automations.

You’re now fully running Home Assistant OS on your Raspberry Pi 5 via KVM—unlocking advanced features and flexibility right from the start!

Troubleshooting and Tips

If you encounter issues with network or UEFI, double-check firmware settings and ensure you are using non-secure boot firmware on ARM.
Management via Cockpit (https://rpi5:9090/) is recommended for visual control.
Make sure your user is in the libvirt and kvm groups for permission to manage VMs.
Monitor the VM’s resource use and logs (sudo virsh console haos).

References

Now your Raspberry Pi 5 is running Home Assistant OS inside a powerful KVM virtual machine!