2025.5.3
Home ▸ Installation ▸

macOS

Install Home Assistant Operating System

Download the appropriate image

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.

  • If VirtualBox is not supported on your Mac, and you have experience using virtual machines, you can try running the Home Assistant Operating System on UTM.

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

  1. Create a new virtual machine.
  2. Select type Linux, subtype Oracle Linux and version Oracle Linux (ARM 64-bit).
  3. 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.
  4. Under Hard Disk, select Use an existing virtual hard disk file, select the unzipped VDI file from above.
  5. Then go to Network > Adapter 1. Choose Bridged Adapter and choose your network adapter (i.e. en0:Wi-Fi).
  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 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.

Start up your virtual machine

  1. Start the virtual machine.
  2. Observe the boot process of the 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 virtual machine’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 now

With the Home Assistant Operating System installed and accessible, you can continue with onboarding.

  Onboarding