# Updating System Software (https://docs.homemanager-app.de/guide/updating-system-software)





A complete Homebridge setup consists of several distinct software components:

* **Homebridge (Core):** The background service handling HomeKit accessory protocol (HAP) communication and running your plugins.
* **Homebridge UI (including API):** The web dashboard and service interface (`homebridge-config-ui-x`) that browsers and mobile apps like Homemanager use to communicate with the server.
* **Node.js:** The JavaScript runtime environment executing Homebridge and all installed plugins.
* **Plugins:** Individual integrations that connect specific accessories and smart home devices.
* **Host operating system:** The underlying system (such as Raspberry Pi OS, Debian, or macOS).

Regular updates resolve security issues, fix bugs, and maintain compatibility with newer iOS releases.

<Callout type="info">
  **HOOBS users:** On HOOBS, you do not need to update Node.js or system packages manually. HOOBS manages all components as a unified package and distributes updates through **HOOBS Core Updates**.
</Callout>

***

## Before you begin: create a backup [#before-you-begin-create-a-backup]

Before applying major updates to Homebridge or Node.js, create a backup of your configuration:

* **In Homemanager (Coming soon):** Open the **Backup** tab to save your instance directly to iCloud Drive or locally on your iPhone or iPad.
* **In the web interface:** Click the three dots in the upper-right corner, select **Backup / Restore**, and download the archive to your computer.

If an update causes unexpected problems, you can restore your working setup immediately.

***

## 1. Managing and applying updates [#1-managing-and-applying-updates]

Homebridge Core, Homebridge UI, Node.js, and plugins are maintained separately.

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Homebridge Web Interface&#x22;, &#x22;Terminal (Command Line)&#x22;]">
  <Tab>
    ### Updating in Homemanager [#updating-in-homemanager]

    In Homemanager, you can manage system software and plugins directly on your iPhone or iPad. Before applying an update, the app always runs an automatic **Compatibility Check**:

    <div className="grid grid-cols-1 sm:grid-cols-2 gap-4 my-6 items-start max-w-lg mx-auto">
      <div className="flex flex-col items-center">
        <ImageZoom src="/images/homebridge/updates/homemanager-system-software.png" alt="Software overview in Homemanager showing Homebridge Core, UI, and Node.js" className="max-w-[210px] rounded-2xl border border-fd-border shadow-md" figureClassName="flex flex-col items-center !my-0 max-w-[210px] w-full" caption="Software overview with update and version controls" />
      </div>

      <div className="flex flex-col items-center">
        <ImageZoom src="/images/homebridge/updates/homemanager-update-compatibility-check.png" alt="Automatic compatibility check before updates in Homemanager" className="max-w-[210px] rounded-2xl border border-fd-border shadow-md" figureClassName="flex flex-col items-center !my-0 max-w-[210px] w-full" caption="Automatic dependency verification before every update" />
      </div>
    </div>

    1. **System components:** Open the **System** tab and select **Software**. Homemanager displays Homebridge (Core), Homebridge UI, and Node.js with their currently installed versions.
    2. **Direct updates:** When an update is available for any component, tap &#x2A;*Update to v...**. This applies to Homebridge and the web interface as well as Node.js.
    3. **Automatic compatibility check:** Before running the update, Homemanager verifies target version requirements against your installed plugins and dependencies. You see right away whether any plugin rules conflict with the new version.
    4. **Version switching & changelogs:** Tap **Changelogs** to review release notes. Tap **Change version** to switch to an earlier release for testing or rollbacks.
    5. **Updating plugins:** Manage your [integrations and plugins](/guide/finding-plugins) in the **Integrations** (or **Updates**) tab. You can review release notes and trigger installations directly there.
  </Tab>

  <Tab>
    ### Updating via the web interface [#updating-via-the-web-interface]

    1. Open the Homebridge web interface in your browser (default port `8581`).
    2. Yellow badges in the top navigation bar and on the **Plugins** page highlight available updates.
    3. Click **Update** to review the release notes.
    4. Confirm the installation. Homebridge restarts the service once the packages are downloaded.
       &#x2A;(Note: For Node.js updates, you can use the built-in terminal directly in the web interface.)*
  </Tab>

  <Tab>
    ### Updating via the terminal [#updating-via-the-terminal]

    Connect via SSH or use the built-in terminal in the web interface to update packages manually:

    ```bash title="Update Homebridge Core"
    sudo npm install -g --unsafe-perm homebridge
    ```

    ```bash title="Update Homebridge UI & API"
    sudo npm install -g --unsafe-perm homebridge-config-ui-x
    ```

    Restart the background service once the update completes:

    ```bash
    sudo hb-service restart
    ```
  </Tab>
</Tabs>

***

## 2. Updating Node.js safely (LTS) [#2-updating-nodejs-safely-lts]

Homebridge runs on the Node.js runtime. For long-term stability, stick to official &#x2A;*LTS (Long Term Support)** releases such as Node.js 20 or 22. Odd-numbered releases (like 21 or 23) are short-lived development branches that often break compatibility with plugins.

### Updating Node.js in Homemanager [#updating-nodejs-in-homemanager]

Homemanager lets you update Node.js directly from your iPhone or iPad:

1. Open the **System** tab and navigate to **Software**.
2. If an update is available or required, tap &#x2A;*Update to v...**.
3. Following the automatic compatibility check, Homemanager executes the installation command on the server in the background. If your setup requires manual permission steps, the app displays the exact terminal commands needed.

### Manual terminal updates (without the app) [#manual-terminal-updates-without-the-app]

For Linux and Raspberry Pi systems, use the official Homebridge utility `sudo hb-service update-node`. System package repositories (`apt`) on Debian often distribute outdated Node.js versions or alter paths used by Homebridge:

```bash
# Automatically update to the latest recommended LTS release
sudo hb-service update-node

# Or target a specific LTS major version
sudo hb-service update-node 22
```

This command identifies the recommended LTS version, downloads and installs the binaries, and rebuilds any native plugin modules that require recompilation. You can run this command via SSH or directly inside the built-in terminal of the Homebridge web interface.

<Callout type="warn">
  **Docker installations:** In Docker environments (such as on a Synology NAS or Unraid), do not run `update-node` inside the container. Pull the latest container image instead:

  ```bash
  docker compose pull && docker compose up -d
  ```
</Callout>

***

## 3. Keeping the host system updated [#3-keeping-the-host-system-updated]

The underlying operating system also requires periodic updates for security patches and network drivers.

On a Raspberry Pi, run the package updates via SSH:

```bash
sudo apt update && sudo apt upgrade -y
```

If a Linux kernel update was installed during the process, restart the machine (`sudo reboot`).

Detailed instructions and environment-specific commands for other host systems are covered in our installation guides:

* [Raspberry Pi setup & maintenance](/guide/install-raspberry-pi#useful-terminal-commands)
* [Docker & container image updates](/guide/install-docker)
* [Synology NAS setup](/guide/install-synology)
* [macOS installation](/guide/install-macos)
* [Windows installation](/guide/install-windows)

***

## Troubleshooting after updates [#troubleshooting-after-updates]

If Homebridge fails to start or gets stuck in a restart loop after an update, inspect the [server logs to pinpoint the issue](/guide/troubleshooting-startup-errors):

### Rebuilding native modules (`NODE_MODULE_VERSION`) [#rebuilding-native-modules-node_module_version]

If your log displays a `NODE_MODULE_VERSION mismatch` error, a plugin depends on a native C++ module compiled for a previous Node.js version. Run the rebuild command:

```bash
sudo hb-service rebuild
```

### Rolling back a version [#rolling-back-a-version]

If a newly installed Core, UI, or plugin release introduces issues:

* **In Homemanager:** Open **System > Software**, tap **Change version** on the affected component, and select the previous version.
* **Via terminal:** Reinstall a specific version explicitly using npm:
  ```bash
  sudo npm install -g --unsafe-perm homebridge@2.1.0
  ```
* Alternatively, restore the backup you created earlier.

<Cards>
  <Card icon="<ShieldCheck />" title="Using Child Bridges" description="Isolate plugins into separate background processes so an individual failure never brings down your entire server." href="/guide/child-bridges" />

  <Card icon="<TriangleAlert />" title="Server Won't Start?" description="Step-by-step solutions for boot loops, port conflicts, and reading errors in the server log." href="/guide/troubleshooting-startup-errors" />
</Cards>