Disclosure: Some of the links on this site are affiliate links. This means that, at zero cost to you, I will earn an affiliate commission if you click through the link and finalize a purchase.

Run Home Assistant on macOS with a Debian 12 Virtual Machine

Welcome to the definitive guide on running Home Assistant on macOS using a Debian 12 virtual machine! If you’re eager to transform your Mac computer into a smart home hub, this article is your roadmap to success.

In today’s interconnected world, home automation has become an essential aspect of modern living.

Home Assistant, a powerful open-source platform, empowers you to seamlessly control and monitor various smart devices from a single centralized interface.

While Home Assistant is traditionally deployed on dedicated hardware like Raspberry Pi, we will take a unique approach by running it on macOS through a Debian 12 UTM virtual machine.

This step-by-step tutorial will demystify the process, making it accessible to both beginners and seasoned tech enthusiasts.

From setting up the virtual machine to installing and accessing Home Assistant for your specific needs, this article has got you covered!

In this article, you can expect to find:

  1. A brief introduction to virtual machines and how they can be used to run Home Assistant on Mac.
  2. A detailed guide on how to create a virtual machine using a freely available program called UTM.
  3. Step-by-step instructions for installing and configuring the Debian Linux operating system within a virtual machine.
  4. Step-by-step instructions for installing Home Assistant on a Debian virtual machine.
  5. How to configure the virtual machine network settings to access Home Assistant from other devices.
  6. Further resources and troubleshooting.

By the end of this journey, you’ll have a fully functional Home Assistant instance running on macOS, opening up a world of possibilities to enhance your home’s efficiency, security, and comfort.

Home Assistant on Mac: How Does it Work?

Home Assistant can be set up and run on macOS using a virtual machine with a freely available open source application called UTM.

UTM is a virtualization application that allows you to run various operating systems, including Windows and many Linux distributions, on macOS devices with both Apple Silicon (M1/M2) and Intel processors.

Here’s an overview of how Home Assistant works on macOS using UTM:

  1. Install UTM on macOS: To begin, you’ll need to download and install the UTM application from the Mac App Store. UTM provides a user-friendly interface for setting up and managing virtual machines.
  2. Set up a new virtual machine: With UTM installed, you can create a virtual machine and choose Debian 12 as the guest operating system. Debian is a popular Linux distribution known for its stability and versatility.
  3. Configure the Virtual Machine: During the virtual machine setup process, you’ll need to allocate resources such as CPU cores, RAM, and storage to the Debian guest. The performance of Home Assistant will depend on these resource allocations.
  4. Install Debian 12 in the Virtual Machine: Once the virtual machine is configured, you can install Debian by following the standard Debian installation procedure.
  5. Install Home Assistant: After Debian 12 is installed, you can access the Linux environment within the virtual machine. From there, you’ll follow the standard installation instructions for Home Assistant on Linux.
  6. Configure the network: To enable communication between Home Assistant and external devices, you will need to configure bridged networking in UTM. This ensures that Home Assistant services are accessible from both your macOS environment and other devices on your local network.
  7. Accessing Home Assistant on macOS: Once Home Assistant is up and running within the Debian virtual machine, you can access the Home Assistant web interface through your macOS web browser. This interface serves as the central hub for managing your smart home devices and automations.
  8. Enjoy Smart Home Automation: With Home Assistant successfully running on macOS through UTM, you can now control and monitor your smart home devices seamlessly from your macOS computer.


In order to get Home Assistant running on your Mac, you will need a Mac which meets the minimum system requirements of UTM and adequate disk space:

  • Apple Silicon (M1/M2 etc…) or Intel processor
  • Requires macOS 11.3 or later
  • Recommended 32GB or more free disk space
  • 4GB of RAM

Downloading Debian 12

To install Debian on a virtual machine, you will need the Debian 12 installation image. You will need to choose the correct version that matches your Mac’s processor architecture.

If you have an Apple Silicon Mac (M1/M2 etc..) then you will need the ARM architecture version. If you have an Intel Mac then you will need the AMD architecture version

If you are not sure which architecture you need, you can find out what processor you have by opening the macOS Terminal and entering the following command:

uname -m

This will output the architecture that you are using. Next, go ahead and download the Debian installation disk image (.iso file) for the architecture that matches your system:

Downloading UTM

You will also need to download and install UTM, which is the macOS application that actually creates the virtual machine. Once downloaded, place the UTM app in your applications folder and launch it from there.

UTM is open source and is completely free to download and use. However if you wish to support the project, there is a paid version available on the app store for a small fee.

The app store version does not have any additional features, but you will benefit from automatic updates.

Creating a New UTM Virtual Machine

Once you have installed UTM, the next thing to do is create a new virtual machine for running Debian. You can start this process whilst you wait for Debian to download, if you are still downloading it.

Add a new virtual machine

In order to add a new virtual machine in UTM, click the ‘+’ button at the top of the main window, or choose Create a New Virtual Machine from the main screen:

Add a new VM in UTM

Next, select the virtualization option by clicking the large button:

Create a virtualized VM

Choose an operating system

On the next screen we are given the option to choose the type of operating system, which can help to simplify the configuration.

Debian is a Linux distribution, therefore you can go ahead and choose Linux for the operating system.

Create a virtualized VM

Choose the boot image

Next, we need to supply UTM with the disk image that contains the Debian installation image.

Click the Browse button and locate the Debian .iso installation image file and select it. Then click Continue to move to the next section.

Select the .iso image

Choosing the hardware settings

Next, we will configure the hardware settings for our virtual machine. In most cases you can use the system requirements given by Home Assistant:

  • 2 GB RAM
  • 32 GB Storage
  • 2vCPU

On the first screen, set the Memory to 2000MB (2GB) or greater. Set the CPU cores to 2, or leave it blank to let UTM manage the number of cores used.

Set the amount of RAM

On the next screen, set the drive size to a value of your preference with a minimum of 32GB as per the Home Assistant system requirements.

Set the hard disk size

Note that you can always change these settings at a later date if you prefer. In some cases you will need to allocate more system resources for more intensive tasks, such as video processing.

Changing RAM and CPU cores is very easy, it can be done from the virtual machine settings in UTM.

However changing the hard drive is more complicated, therefore I would recommend setting it to the size that you require at this stage.

If you do need to change the disk size at a later date, you can learn how to do it in my article about resizing UTM virtual drives.

Choosing a shared location

There is no need to set up file sharing between the virtual machine and your macOS host, as file sharing can be set up later in Home Assistant.

Therefore you can skip this screen and just click continue.

Finalizing and starting the VM

On the final screen you have the opportunity to give your new VM a name, such as Home Assistant. You can review the settings and then click save to add your new virtual machine to UTM.

Next, we can start the newly created virtual machine. Select the VM from the left-hand sidebar menu and then click the play button to boot up the virtual machine.

Note that the default display and network settings should be adequate to get things up and running. You can adjust these at a later point if necessary.

Installing Debian on a UTM Virtual Machine

Once you have created and booted up the new virtual machine, the Debian installation will begin.

  1. Choose Install to begin the installation (you can use Graphical Install if you prefer).
Begin the Debian Installation

Set up Languages and Location

  1. First, choose the default system language. This will also be the language used for the installation process:
Choose the system language
  1. Choose your home country. This location will be used to set your time zone and other aspects of the system that are dependent on location.
Choose the geographic location
  1. Choose your keyboard layout.
Choose the keyboard layout

Set Up the Accounts

  1. The hostname is a single word that usually describes the system and can be thought of simply as a name for the system. For this example I will use the default hostname debian.
Enter a hostname
  1. A domain name is not required, leave this blank and press enter to continue.
  2. Enter a password for the root user. Re-enter the password when prompted in order to confirm. It is important that you make a note of this password and keep it safe somewhere as it can be used to log in to the root account and perform any necessary system tasks.
  3. Enter a name for the system user account. This would usually be your real name, however in this example I will use debian.
Enter a name for the user account
  1. Enter a username for the user account. This will be the username that you use to login to Debian. In this example I will create the username user.
Enter a username for the user account
  1. Enter a password for the user account. This will be the password used to login to Debian. Re-type the password when prompted to confirm.

Set Up the Timezone

  1. Choose your timezone. If you do not see the correct timezone listed, you will need to go back and change the system language. Note that you can change the timezone after installation using the Debian command line.
Set the Debian timezone

Create the Disk Partitions

  1. Next, Debian will create the disk partitions. Choose the guided – use entire disk option.
Partition the disk using guided partition mode
  1. Choose Virtual Disk 1, it should be the only option available.
Partition virtual disk 1 (vda1)
  1. Choose the option to put all files in one partition.
Put all files in a single partition
  1. You will be shown a summary of the partition settings. Select finish partitioning and write changes to disk and then choose yes in order to complete the process.
  2. Next, the base files will be installed and package manager will be configured. When prompted to scan extra installation media, choose no.
Additional installation media is not required

Choose a Mirror

  1. Next, Debian will connect to the internet to fetch the required files. In order to do this it will connect to one of the available mirrors. Choose the region closest to you in order to select the best mirror. This is not essential, but can speed up the installation process.
Choose a mirror location
  1. Select a mirror from the list. If you are unsure of the best mirror to use, just choose deb.debian.org.
  2. When prompted to choose a proxy, just leave it blank and choose continue.
Choose a mirror

Complete the Installation

  1. Debian will now proceed to download and install the necessary files. When prompted to opt in to the popularity contest, you can choose whether or not you wish to take part. Including yourself in the popularity contest can help the Debian developers, however it is not mandatory. If in doubt, just choose no.
Opt in or out of the popularity contest
  1. You will now be given the choice of software tools that you wish to include. In this example we will not opt to install a GUI, as this can be done after the installation. Therefore ensure that only SSH server and standard system utilities are selected. Choose Continue to begin the installation.
Choose software to install
  1. Once the installation has completed you will be prompted to remove the installation media before continuing. Do not click continue yet. First you need to remove the installation media from UTM. From the main UTM window, click the CD/DVD dropdown and then click clear. This will remove the Debian installation .iso file from the virtual CD drive.
Remove installation media
  1. Once you have removed the installation media, click continue to complete the installation.
Remove installation media
  1. The virtual machine will restart and take you to the Debian command prompt. Here you can log in with the credentials you created earlier in order to get to the command prompt.
Debian 12 Command Line

Installing Home Assistant on Debian 12

At this stage you should have a working virtual machine and you should be able to access the Debian command line. The next step is to install Home Assistant.

First, you will need to login to Debian using the credentials you created during the installation. Enter your username and password to login to the Debian command line.

Next, enter the following command to display the IP address of the virtual machine.

hostname -I

The IP address will most likely be something like 192.168.64.X.

Now that you have your virtual machine IP address, you can log into it using the macOS Terminal.

To do this, open a new macOS terminal window and enter the following command, replacing <username> with your Debian username and <IP-address> with the IP address from the previous command.

ssh <username>@<IP-address>

Note that using the macOS terminal is not essential and you can enter everything directly into the Debian virtual machine. However using the macOS terminal instead makes things much easier, as you can easily copy and paste commands.

For the first few tasks we need to be logged in as root, which we can do with the following command:

su -

You will need to enter the credentials that you chose during installation.

Install Dependencies

Firstly, we need to install all of the system dependencies that are required by Home Assistant. This can be done with the following command.

apt install \
apparmor \
jq \
wget \
curl \
udisks2 \
libglib2.0-bin \
dbus \
lsb-release \
systemd-journal-remote \
systemd-resolved \
network-manager -y

Note that the Home Assistant developers sometimes amend the list of dependencies.

If something is added and the command above becomes out of date, you may encounter a missing package/dependency error during the installation of Home Assistant later in the tutorial.

If you do encounter this error, you can resolve the issue by checking the official list of required dependencies. Simply copy and paste the command from there instead and then try the Home Assistant installation again.

Update Networking Settings

Once the dependencies are installed, we need to move control of the network interfaces over to Network Manager. First, we need to remove the interfaces configuration.

mv /etc/network/interfaces /etc/network/interfaces.bak

Next, we will reboot the virtual machine.

reboot now

Once the virtual machine has rebooted, log back in and switch to the superuser account again.

su -

Install Docker-CE

Next, we will install Docker-CE with the following command.

curl -fsSL get.docker.com | sh

Install OS-Agent

The Home Assistant OS-Agent acts as a communication channel between the operating system and the Home Assistant Supervisor. It allows the Home Assistant Supervisor to interact with and control the operating system functionalities.

We will need to install the OS-Agent, which is used to connect the Debian operating system to Home Assistant.

The easiest way to download the latest version of OS-Agent is by using either of the following commands. Alternatively you can download OS-Agent manually.

ARM architecture:

curl -s https://api.github.com/repos/home-assistant/os-agent/releases/latest | jq -r '.assets[] | select(.name | endswith("aarch64.deb")) | .browser_download_url' | xargs wget

Intel architecture:

curl -s https://api.github.com/repos/home-assistant/os-agent/releases/latest | jq -r '.assets[] | select(.name | endswith("x86_64.deb")) | .browser_download_url'| xargs wget

Manual Download

The commands above will automatically download the latest version of OS-Agent for the specified architecture using the GitHub API. If for any reason these commands don’t work, you can also download OS-Agent manually.

To do this, first go ahead and visit the releases download page and locate the correct package for your architecture. You will need the package with a .deb extension in order to install it on Debian.

Right-click the package and copy the link address, then use this address with the wget command.

wget <OS-agent URL>

For example, at the time of writing the current version is 1.2.2, therefore the command would be as follows.

wget https://github.com/home-assistant/os-agent/releases/download/1.2.2/os-agent_1.2.2_linux_aarch64.deb

Installing OS-Agent

Once the package has downloaded, we can install it with dpkg followed by the package name. Replace <os-agent-version> with the version of OS Agent that you are using.

dpkg -i os-agent_<os-agent-version>.deb

Once complete, you can test the installation with the following command.

gdbus introspect --system --dest io.hass.os --object-path /io/hass/os

This command should not produce and error. The output should look something like the following.

Correct OS-Agent output

Install Home Assistant Supervised

The last thing remaining to do is install Home Assistant. This can be done with the Home Assistant supervised Debian package.

First we can go ahead and download the package using wget.

wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb

Once the download has completed, we can install it with dpkg.

dpkg -i homeassistant-supervised.deb

Choose a machine type

You may need to select a machine type. For Apple Silicon Mac builds running Debian arm64, choose qemuarm-64. For Intel Mac builds running Debian x86_64, choose qemux86-64.

Choose the correct architecture

Once the installation has completed, Home Assistant will start up but it will take a few minutes before we can access it.

The IP address of our Home Assistant server is given at the end of installation, in my case

Home Assistant Supervised installation complete

In order to check that the installation was successful, go ahead and visit the IP address using a browser.


So in my case it would be as follows.

Home Assistant onboarding

Configuring Bridged Mode Networking

By default the VM is configured to use a network mode called “shared network” as it offers the most compatibility out of the box.

This mode creates a virtual network between the guest OS (Debian) and the host OS (Mac OS) and provides the guest OS with access to the internet.

One disadvantage to this method of networking is it does not allow devices on your local network outside of the host OS to access the guest OS, which means you can only access Home Assistant from the browser on your host OS.

The following diagram can help you better understand the difference between the network modes:

UT Network Modes

In order to access Home Assistant from other devices on your local network (the mobile app, other computers on the network or IP-based smart devices), the Debian guest operating system should have it’s own IP address on your external network that is in the same subnet, for example 192.168.1.X.

This can be achieved by changing the networking mode. You can change the network mode with the following steps:

  1. Shut down the Home Assistant Debian virtual machine if it is currently running.
  2. Right click the Home Assistant Debian virtual machine on the left-hand sidebar and click edit.
  3. Under Devices, click Network to show the network settings.
  4. In the Network Mode drop down list, change the setting to Bridged (Advanced) and then click Save.
  5. Start the Home Assistant Debian virtual machine.

When you boot the virtual machine with the new network settings, the IP address assigned should now match your local area network and you should be able to connect from external devices, such as other computers or the mobile app.

Bridged network mode and Ethernet

If you want to switch to bridged networking mode and use Ethernet, you will need to complete an additional step. By default UTM will create a network bridge to your WiFi adapter

If you have both WiFi and wired network connections (Ethernet) on your Mac and you want to use Ethernet, you will need to manually change the network bridge so that it uses Ethernet.

In mostly all cases the WiFi interface is called en0 and the Ethernet is called en1.

To connect the network bridge to ethernet, simply enter en1 as the value for Bridged Interface on the Network settings menu.


In conclusion, running Home Assistant on macOS with a Debian 12 virtual machine offers a compelling and accessible approach to creating a smart home hub within your existing computing environment.

By harnessing the power of virtualization through UTM, you can seamlessly integrate Home Assistant into your macOS ecosystem and gain control over a diverse range of smart devices from a centralized interface.

Throughout this journey, we have explored the intricate workings of this setup, from configuring the virtual machine and installing Debian 12 to setting up Home Assistant as the heart of your smart home automation.

The flexibility and convenience of this approach eliminate the need for dedicated hardware, making it an enticing option for both newcomers and experienced enthusiasts.

Embrace the power of Home Assistant on macOS with a Debian 12 virtual machine, and let your home thrive in the world of interconnected possibilities. It’s time to experience the magic of home automation at your fingertips. Happy automating!

Thanks so much for visiting my site! If this article helped you achieve your goal and you want to say thanks, you can now support my work by buying me a coffee. I promise I won't spend it on beer instead... 😏

9 thoughts on “Run Home Assistant on macOS with a Debian 12 Virtual Machine”

  1. Thanks for this.

    USB devices don’t seem to work though. I’m trying to get my USB Zigbee dongle to work, but when I try to add the integration “Zigbee Home Automation” it asks me for the “serial device path”. How do I find this out?


    1. Which Zigbee stick are you using? I just tested SONOFF ZBDongle-P on Home Assistant 2023.7.3, UTM 4.2.5 and Debian 12, using the Zigbee Home Automation integration and everything worked fine. I did not have to manually enter any details about the device.

      However for reference, if you do need it then entering ls /dev/ttyUSB* into the Debian terminal should reveal the Zigbee stick serial device path.

      1. Strange, I’m using the same stick, and the same version of everything, running on an M1 mini. I tried entering that command, but it says:
        ls: cannot access ‘/dev/ttyUSB*’: No such file or directory.

        Are there particular USB settings I need in UTM?

        1. That probably means that Debian is not recognizing the stick. When you plug the stick in, are you doing so with the virtual machine window in focus, so that UTM asks you if you want to connect the stick to the virtual machine or your Mac? Alternatively you need to select the device by pressing the little USB icon in the top right of the virtual machine window. More info here: https://docs.getutm.app/guest-support/sharing/usb

          1. Thanks! I think you’re right. I started the VM, and then plugged in the stick while it was in focus, confirmed that dialog, then sure enough it turned up in Discovered for easy setup.

            One question: would I need to do this every time there’s a restart?

          2. Great! Glad it worked for you. As for restarting, I believe at present you would need to reconnect the USB to UTM after restarting, however the developers are discussing adding the ability to ‘bookmark’ a USB device so that it also autoconnects on boot. It may also be possible to do this directly by modifying the QEMU command, perhaps something I could look in to.

            More info here: https://github.com/utmapp/UTM/issues/3400

  2. Hi Simon

    Thanks heaps for this! I have an intel mac and I followed your steps.

    I noticed that after some time my home assistant loses its connection against the devices. When I go to the home assistant logs… it just says “device is unavailable”. I can still access the home assistant page through the browser but all the devices are not connected. I tested pinging the home assistant (using Fing app) and it is not able to be pinged. However when I reboot the linux VM then everything goes back to normal but then it eventually loses connection to devices.

    Any thoughts on how I can diagnose the issue and potential fix? I am so lost. I have a deco router

  3. Hi Simon

    Thanks heaps for this! I have an intel mac and I followed your steps.

    I noticed that after some time my home assistant loses its connection against the devices. When I go to the home assistant logs… it just says “device is unavailable”. I can still access the home assistant page through the browser but all the devices are not connected. I tested pinging the home assistant (using Fing app) and it is not able to be pinged. However when I reboot the linux VM then everything goes back to normal but then it eventually loses connection to devices.

    Any thoughts on how I can diagnose the issue and potential fix? I am so lost. I have a deco router

  4. Thanks very much for the tutorial. I am trying to install and once I have set up the VM and installed Debian, I try to log in on Terminal with my username and the IP address and it says “zsh: parse error near `\n’ ” and I cannot get any further. Have I made an error earlier?

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top