Homebridge requires Node.js installed on your system to run. From time to time, you will need to update the Node.js runtime to enable support for new features.

Homebridge (and verified plugins) support all current Active and Maintenance LTS releases of Node.js. At the time of writing, this means we will support:

• Node.js 16.x until September 2023
• Node.js 18.x until April 2025
• Node.js 20.x from October 2023 until April 2026
• Node.js 22.x from October 2024 until April 2027

Homebridge does not support odd-numbered releases of Node.js, such as 19.x and 21.x.

Updating Node.js is not a risk-free exercise, so it is recommended users only do so when required.

• If you are running Node.js v14.x or v16.x, now is a good time to update.
• If you are running Node.js v18.x there is no urgent need to update, as we will still be supporting this version until April 2025, however, you can still do so if you like.

If you are running an older operating system you will not be able to update your NodeJS installation until your operating system is updated, and the update-node command will fail with Your version of Linux does not meet the GLIBC version requirements to use this tool to upgrade Node.js.

To check your GLIBC version you can run the command getconf GNU_LIBC_VERSION on Linux and Raspbian platforms.

To update your GLIBC version, this will require the operating system to be updated prior to updating NodeJS. An operating system update will require rebuilding your setup, but with some simple steps, you will not lose your existing configuration. Creating a Homebridge Archive/Backup and restoring it after the Operating System upgrade will keep your existing configuration and HomeKit settings. Also doing the Operating System upgrade on a new SD card will allow you to keep your existing card as an additional backup.

It is also recommended to shut down your Apple home hubs during the update, and turn on again after the update is complete.

If you have followed one of the Homebridge Install Guides, you can refer back to the guide for your platform to see how to update Node.js.

For Linux and macOS users, we have created a tool to help you update Node.js in a safe way using hb-service (even if you aren't using hb-service to manage the process):

sudo hb-service update-node

This tool will only update Node.js if it can safely do so. If you've installed Node.js in a non-standard way, it will not change your system.

You can roll back to a previous version by appending the version number to the command:

sudo hb-service update-node 18.18.0

Windows 10 users can view update instructions here.

Users running in Docker should update Node.js by pulling down the latest version of the Homebridge Docker Image. Please note that we moved the Homebridge Docker image into the homebridge domain in the spring of 2023, and if your install predates that you will need to update the image location from oznu/homebridge to homebridge/homebridge.

While not recommended, if you are using the "Ubuntu" or "Debian" variant of the image, you can also update inside the container using hb-service update-node and then restart manually. Users running the "Alpine Linux" variant cannot use hb-service update-node.

It is important to update Node.js using the same method you originally used to install it, or using hb-service update-node.

• Do not update Node.js using instructions you found on some random site on the internet.
• Avoid nvm or n - these are great tools for developers, but require additional configuration when running Homebridge as a service user.

Failing to adhere to these guidelines will likely result in you having multiple copies of Node.js installed which will cause many strange problems (if you have done this, see how to fix it on Linux and macOS).