Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Install Homebridge on macOS
Note: This document is a work in progress, and users are encouraged to improve and update.
Installation and configuration steps
1) Install Xcode
- Open the App Store on your macOS device, and install Xcode.
- Open Xcode once, then quit the application.
2) Install homebrew — a package manager for macOS — by opening terminal and running the following command:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Note: If you have issues getting Command Line Tools installed you can resolve it by downloading the package directly. This site has a great guide http://railsapps.github.io/xcode-command-line-tools.html
3) Install Node via homebrew by opening terminal and running the following command:
brew install node
Note: By installing Node via homebrew, you will not need superuser (sudo) permissions when installing Homebridge and Homebridge plugins.
4) Install Homebridge
Open terminal, and run the following command to install Homebridge globally:
npm -g install homebridge(macOS Sierra and earlier)
npm -g install homebridge --unsafe-perm(macOS High Sierra)
If installation proceeds without error, go to step 5.
MDNS install script error
After installing both xcode and nodejs, you may receive the following error message when using the above npm install command:
ERR! node-gyp rebuild","Failed at the firstname.lastname@example.org install script.
To correct this error:
- Open Xcode.
- From the Xcode menu, navigate to Open developer tool > More developer tools
- Login to the Apple Developer website with your Apple ID.
- Once logged in, download and install the Xcode command line tools for your macOS version.
- With Terminal open, re-run the command to install Homebridge.
MDNS install script error instructions for High Sierra Users
In addition to completing the steps above, High Sierra users need to add
--unsafe-perm onto the end of the command line instruction for installing Homebridge, to overcome the MDNS install script error.
For the avoidance of doubt, High Sierra users must use the following command for installation:
npm -g install homebridge --unsafe-perm
For more information, see https://github.com/nfarina/homebridge/issues/1628.
If installing as root
WARNING: Be aware that enabling and using the root account can be dangerous to your operating system, and may require a full erase and install to undo any changes made as the root user.
NOTE: Installation of Homebridge as the root user is not needed. You can safely install and run Homebridge as any normal user of the machine. If Node has been installed using homebrew, using
sudoin any terminal commands to invoke elevated privileges should only be required when adjusting launchd permissions (below).
By default, macOS does not enable the root account. To enable the root user, see https://support.apple.com/en-ca/HT204012.
5) Install Homebridge plugins
Install the relevant Homebridge plugins globally, using the following terminal command:
npm -g install [name of plugin]
To find a list of available plugins, and the information needed for each within the
config.json file, go to:
6) Create the config file
- Enter the following command:
- be sure to change the YourUserName to your particular username
- Paste in the content of the sample config-sample.json
- Delete the entitreity of line 5 (the port number) to avoid any issues with your particular setup.
- Modify the username
- Modify the PIN
ENTERto save your changes.
Refer to the Homebridge Readme for additional instructions on where this file should be located and how to edit it.
Note: If you've created config.json in the wrong location, the correct location will be displayed when you first run Homebridge (see below).
Run Homebridge for the first time
From terminal, run the following command to make sure everything is set up correctly:
If Homebridge runs successfully, you should be able to pair it using the displayed instructions using the Home app on your supported iOS device.
Starting Homebridge automatically with launchd
Create a launchd plist file for Homebridge in
Edit the plist file you just created, adding the following content:
Note: Ensure that you update the
username portion of the path with your username, shown in the String values for the Key StandardOutPath, StandardErrorPath, and HOME.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>RunAtLoad</key> <true/> <key>KeepAlive</key> <true/> <key>Label</key> <string>com.homebridge.server</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/homebridge</string> <string>-I</string> </array> <key>StandardOutPath</key> <string>/Users/username/.homebridge/logfile.log</string> <key>StandardErrorPath</key> <string>/Users/username/.homebridge/logfile.log</string> <key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> <key>HOME</key> <string>/Users/username</string> </dict> </dict> </plist>
Permissions must be correct on ~/Library/LaunchAgents folder and the ~/Library/LaunchAgents/com.homebridge.server.plist file.
sudo chown $(whoami) ~/Library/LaunchAgents
sudo chown $(whoami) ~/Library/LaunchAgents/com.homebridge.server.plist
sudo chmod 700 ~/Library/LaunchAgents
sudo chmod 600 ~/Library/LaunchAgents/com.homebridge.server.plist
Reboot your computer. Homebridge will now start automatically at boot and will restart if it crashes.
Run the following in a terminal to manually start Homebridge background process:
launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist
Run the following in a terminal to manually stop homebridge background process:
launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist
launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist && launchctl load ~/Library/LaunchAgents/com.homebridge.server.plist
Updating Homebridge and plugins
Periodically, Homebridge and its plugins may be updated. To see if there are any updates you can run the following command to see what is available:
npm -g outdated
To update a particular plugin or Homebridge itself, run:
sudo npm -g update [homebridge | name-of-plugin]
To force an update, you can re-install it to force the latest version:
sudo npm -g install [homebridge | name-of-plugin]
You see the error "throw new Error("The requested platform '" + name + "' was not registered by any plugin." on first load
This means that one (or more) of the homebridge platforms or accessories called by your config.json file hasn't been installed.
Check the packages you have installed by running the following command:
npm list -g --depth=0
Compare this against your config.json to ensure all your relevant packages are installed.
Once you've identified the missing package, return to Step 5 above to install the missing package.
Creating and viewing logfiles
If you used launchd to run Homebridge (as described above), then the log files for your Homebridge installation will be available at:
username with the username which Homebridge is running under.
To view the log file, load it using your preferred viewer. From Terminal - you can run the following command to view the log file as it is updated:
tail -f ~/.homebridge/logfile.log
iOS Home app showing Updating...
Often, you may find that when loading the iOS Home app, the devices exposed using homebridge will show the status of
Updating... for a long period of time.
To overcome this, using Terminal, run the following command to prevent the computer homebridge is installed on from going to sleep:
sudo systemsetup -setcomputersleep Never
If you need to uninstall Homebridge, ensure the Homebridge server is first stopped - either by:
- If started from the terminal window, pressing Command + C to quit the process, OR
- If started using launchd, running the following command:
launchctl unload ~/Library/LaunchAgents/com.homebridge.server.plist
Once Homebridge is stopped, run:
npm uninstall -g homebridge
Note: This may not remove configuration files, or logs, and the user may need to remove these manually.
Removing platforms required for Homebridge
For information on removing NPM, see: https://docs.npmjs.com/misc/removing-npm
You may need to do some research to work out how to uninstall this if you need to.