Skip to content

Install Homebridge on macOS

oznu edited this page Jul 13, 2022 · 108 revisions
Clone this wiki locally

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.


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 -v

Step 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

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

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