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
Prerequisites
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.
Installing Homebridge
Step 1: Install Node.js
Homebridge requires Node.js installed on your system to run. Download the LTS version of Node.js (v16.16.0) and run the installer with all the default options selected:
Download Node.js v16.16.0 macOS Installer
From a Terminal window test that Node.js is working:
# test node.js is working
node -v
# test npm is working
npm -vStep 2: Install Homebridge and Homebridge UI
Install Homebridge and the Homebridge UI using the following command:
sudo npm install -g --unsafe-perm homebridge homebridge-config-ui-x
To setup 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 setup Homebridge and the Homebridge UI as a service.
The Homebridge service will be setup using the user account you are currently logged in as and does not require sudo/root privileges once setup.
The Homebridge config.json can be found under ~/.homebridge and will be created automatically if it does not already exist.
Complete: Login to the Homebridge UI
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.
How To Uninstall Homebridge
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
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.
Major Node.js Version Updates
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 Configuration Reference
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 |