In this procedure you will install the Home Assistant software application and run it as a background process directly on MacOS. While the entire installation takes place at the Terminal command prompt, it’s actually very easy — only five commands!
Since both HAOS and Docker install methods under MacOS require a virtual machine, Core python is the only “native” (non-hypervisor) method of running HA on MacOS. Note that HA Core does not support Add-ons, or even containers, so this is a very “basic” installation method but it runs very fast on Apple Silicon (arm64) hardware.
Procedure last updated: April 2025 with HA core-2025.4.1 and Python 3.13.
Prerequisites: Homebrew (currently) requires MacOS Ventura 13.6 or later.
Feel free to comment below with any suggestions or improvements. If you have issues running this procedure, please consider opening a new topic asking the community for support with your specific problem(s). If you include a link to this Topic in your post, we can find and review your problem(s) in order to update and improve this procedure.
————–
Step 1: Install Homebrew
Open the MacOS Terminal app and run the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
For troubleshooting, details, or other installation methods, consult the Homebrew website and discussions.
Step 2: Install pipx
The pipx utility is an installer for Python apps with a pre-configured “virtual environment” (venv) to give the app a “sandbox” and prevent it from interacting with the rest of your system’s Python libraries. In addition, pipx can use the homebrew version of python that HA needs, rather than whatever version of python shipped with your version of MacOS, allowing you to leave that alone.
In the Terminal app, run the following commands:
brew update
brew install pipx
Step 3: Install Home Assistant
In the Terminal app, run the command:
pipx install homeassistant
The install will take a few minutes to download all dependencies. Files are installed into your MacOS home directory, under ~/.local/pipx/venvs/homeassistant
Step 4: Enable autostart
In the Terminal app, run the command:
hass --script macos install
This runs a HA script to configure MacOS’s launchctl to start the application whenever you login to your Mac. You should also find a new option in the “Login Items” of the Settings app to toggle “hass” autostart on login. Home Assistant should now be running.
The first time HA starts, it may take a minute or two to setup all the configuration files. It may also ask permission for Python to accept connections (if your MacOS firewall is enabled), and to use your system bluetooth.
Step 5: Fix some errors
When you login to HA, you may see a few errors in the logs. These may be harmless, but if they bother you, continue reading this section.
No such file or directory: ffmpeg — run the following commands:
brew install ffmpeg
which ffmpeg # note the path to the program for later
ffmpeg # needs to be run at least once manually
Then edit ~/.homeassistant/configuration.yaml to specify the path to ffmpeg, for example:
ffmpeg:
ffmpeg_bin: /opt/homebrew/bin/ffmpeg
And restart Home Assistant.
zlib_ng and isal are not available, falling back to zlib, performance will be degraded — run the following commands:
python3 -m venv ~/.local/pipx/venvs/homeassistant
source ~/.local/pipx/venvs/homeassistant/bin/activate
python3 -m pip install isal
deactivate
And restart Home Assistant.
Apple Unknown MacOS Model (Core Bluetooth) in the Bluetooth integration may be due to a bug or lack of drivers for my M2 Pro. Feedback welcome if bluetooth works for you.
Maintenance
Some useful information for maintaining your MacOS HA Core installation:
Your configuration directory defaults to ~/.homeassistant
Logs are stored in ~/Library/Logs/homeassistant.log
Backups can be configured in the GUI settings page.
To perform updates — after you have made a backup — run the following commands:
brew update
brew upgrade
pipx upgrade homeassistant
You can also stop and start the service manually using launchctl at the Terminal:
launchctl unload ~/Library/LaunchAgents/org.homeassistant.plist ## stops HA
launchctl load ~/Library/LaunchAgents/org.homeassistant.plist ## starts HA
launchctl kickstart -k gui/$UID/org.homeassistant ## restarts HA if running
Other guides for installing HA on MacOS:
- Using VMware Fusion virtual machine
- Using UTM virtual machine, a free GUI for qemu
- Using Colima Containers, an open alternative to Docker engine for MacOS
- Using Official documentation — Note this contains many errors as of last check (it appears to just be a copy/paste of the Linux procedure) and should not be used.
This is a community guide, not a tech support thread. If you get errors running this procedure, please consider opening a new topic, that links to this procedure, rather than commenting with tech support questions. Your topic’s link will appear just below this paragraph allowing maintainers to review your post and update this procedure with any issues and corrections. Feel free to comment with suggestions or fixes. Thanks!