2026.2.1
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 app needs).

Minimum recommended assignments:

  • 2 GB RAM
  • 2vCPU

All these can be extended if your usage calls for more resources.

Hypervisor specific configuration

Create the virtual machine

  1. Open VirtualBox and click the New button (the blue star).
  2. Name: Type Home Assistant.
  3. ISO Image: Leave this as None or Empty.
  4. Type & Version: Select Linux, then select Oracle Linux (64-bit) (or ARM 64-bit if you are using a Mac with an M1/M2/M3 chip).
  5. Click Next.

Configure hardware

  1. Base Memory: Move the slider to at least 2048 MB (2GB).
  2. Number of CPUs: Move the slider to at least 2.
  3. EFI: Check the box for Enable EFI (special OSes only). This is required for Home Assistant to boot.
  4. Click Next.

Finalizing the wizard

  1. On the Virtual Hard Disk screen, leave the settings as they are (it will suggest creating a new disk). We will swap this for your downloaded file in the next step.
  2. Click Finish.

Attach the Home Assistant disk (VDI)

  1. Click on your new “Home Assistant” VM in the left-hand list and click the Settings icon (the orange gear).
  2. Go to the Storage section on the left menu.
  3. In the “Storage Devices” list, you will see a disk already listed under Controller: SATA. Right-click that disk and select Remove Attachment. This removes the empty placeholder disk.
  4. Click the Add Hard Disk icon (the small disk with a green plus symbol) located next to the words “Controller: SATA”.
  5. In the window that pops up, click the Add button at the top.
  6. Find and select the .vdi file you previously downloaded and unzipped.
  7. Click Choose to confirm the file.

Configure network

  1. While still in the Settings window, go to the Network section.
  2. Change the Attached to setting from “NAT” to Bridged Adapter.
  3. Under Name, select the adapter you use for internet access. This allows Home Assistant to talk to other devices in your home.
  4. Click OK.

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).

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

  Onboarding