Install Homebridge on macOS
This guide provides step-by-step instructions to show you how to install Homebridge on macOS as a service so it will automatically start on boot.
- Prerequisites
- Installing Homebridge
- How To Uninstall Homebridge
- Multiple Instances
- Major Node.js Version Updates
- Configuration Reference
Before you get started, make sure you have the following ready:
- A computer running a recent version of macOS that is always powered on.
- Access to the terminal. You can find the Terminal app using launch pad. You will need the ability to copy and paste commands from this guide into the terminal.
- This guide is intended to be used on machines that do not yet have Homebridge installed. Please make sure you remove any existing installations of Homebridge before you get started.
- Apple Silicon / M1 devices are supported natively.
Homebridge requires Node.js installed on your system to run. Download the LTS version of Node.js (v20.9.0) and run the installer with all the default options selected:
From a Terminal window test that Node.js is working:
# test node.js is working
node -v
# test npm is working
npm -vInstall Homebridge and the Homebridge UI using the following command:
sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x
To set up Homebridge as a service that will start on boot you can use the provided hb-service command.
sudo hb-service install
This command will do everything that is required to set up Homebridge and the Homebridge UI as a service.
The Homebridge service will be set up using the user account you are currently logged in as and does not require sudo/root privileges once set up.
The Homebridge config.json can be found under ~/.homebridge and will be created automatically if it does not already exist.
Login to the web interface by going to http://localhost:8581.
The Homebridge UI web interface will allow you to install, remove and update plugins, and modify the Homebridge config.json and manage other aspects of your Homebridge service.
Review the Configuration Reference at the bottom of this guide.
To remove the Homebridge service run:
sudo hb-service uninstall
To remove Homebridge and Homebridge Config UI X run:
sudo npm uninstall --location=global homebridge homebridge-config-ui-x
💡 Homebridge now supports Child Bridges which are an easier-to-manage alternative to running multiple instances.
Some users like to run multiple instances of Homebridge.
The hb-service command makes this easy to do via the --service-name flag.
See the hb-service documentation for instructions.
It is recommended to run Homebridge on the current stable LTS version of Node.js. You can update Node.js to the current LTS version of Node.js by running:
sudo hb-service update-node This table contains important information about your setup. You can use the information provided here as a reference when configuring or troubleshooting your environment after setting up Homebridge using the instructions below.
| File Location / Command | |
|---|---|
| Config File Path | ~/.homebridge/config.json |
| Storage Path | ~/.homebridge |
| Restart Command | sudo hb-service restart |
| Stop Command | sudo hb-service stop |
| Start Command | sudo hb-service start |
| View Logs Command | hb-service logs |
| Launchctl Service File | /Library/LaunchDaemons/com.homebridge.server.plist |
Click here for the configuration reference for setups done before January 2020
| File Location / Command | |
|---|---|
| Config File Path | ~/.homebridge/config.json |
| Storage Path | ~/.homebridge |
| Restart Command | Run the stop and start commands |
| Stop Command | launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist |
| Start Command | launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist |
| View Logs Command | tail -f ~/.homebridge/homebridge.log |
| Launchctl Service File | ~/Library/LaunchAgents/com.homebridge.server.plist |