# Finding and Setting Up Homebridge Plugins (https://docs.homemanager-app.de/guide/finding-plugins)





Homebridge links smart devices without native Apple Home support to HomeKit, relying on plugins to communicate with hardware from brands like Shelly, Philips Hue, Roborock, and Ring.

The community provides thousands of plugins for almost any smart accessory. The following walkthrough shows how to choose maintained plugins, verify version compatibility, and complete setup using Homemanager, the web interface, or the command line.

***

## Searching and Installing Plugins [#searching-and-installing-plugins]

You can install plugins through three different methods:

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Homebridge Web Interface&#x22;, &#x22;Command Line (CLI)&#x22;]">
  <Tab>
    ### Setup with Homemanager [#setup-with-homemanager]

    On iPhone and iPad, Homemanager combines plugin discovery with guided configuration:

    <div className="grid grid-cols-2 lg:grid-cols-4 gap-4 my-6 items-start">
      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/plugins/homemanager-my-integrations.png" alt="Integrations overview with Integration Store banner" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="1. Integrations & Store banner" />
      </div>

      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/plugins/homemanager-integration-store.png" alt="Integration Store with Trending and Popular categories" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="2. Integration Store & categories" />
      </div>

      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/plugins/homemanager-plugin-search.png" alt="Searching for plugins in Homemanager" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="3. Targeted search for devices" />
      </div>

      <div className="flex flex-col items-center text-center">
        <ImageZoom src="/images/homebridge/plugins/homemanager-plugin-sorting.png" alt="Sorting by Trending, Popular, and Updated" className="max-w-[190px] rounded-2xl border border-fd-border shadow-md" caption="4. Sorting and filtering" />
      </div>
    </div>

    1. Open the **Integrations** tab in Homemanager and tap the **Integration Store** banner at the top.
    2. Browse the **Trending** and **Popular** sections, or use the search bar to locate a specific model or manufacturer (such as `Shelly` or `Hue`).
    3. Filter results using the top chips (**All**, **Verified**, **Guided Setup**) and use the sort sheet to organize by popularity, trend, or update date.
    4. Check the badge indicators next to each plugin:
       * **Green shield:** Homebridge Verified Plugin (meets official quality and stability guidelines set by the Homebridge project).
       * **Purple shield:** Maintained directly by the Homebridge core developer team.
       * **Orange icon:** HOOBS Verified Plugin (verified for reliable operation on HOOBS).
       * **`[A]` symbol:** Guided Setup (includes a visual configuration form via `config.schema.json`).
    5. Select your chosen plugin and tap **Install**.
    6. After the download completes, Homemanager interactively guides you through setting up a Child Bridge for the integration.
    7. Next, the configuration form opens so you can enter IP addresses or authentication tokens and save your settings.

    <Callout type="info">
      A card displaying **Configuration pending** indicates that the plugin is installed on your server, but still requires mandatory settings before it can launch. The **Used in X bridges** note shows how many bridge instances or child bridges currently run this integration.
    </Callout>

    <div className="my-5 flex flex-wrap items-center gap-3">
      <AppStoreButton size="sm" />

      <span className="text-xs text-fd-muted-foreground">
        Discover & install plugins on mobile with Homemanager
      </span>
    </div>
  </Tab>

  <Tab>
    ### Setup via the Web Interface (Config UI X) [#setup-via-the-web-interface-config-ui-x]

    If you are on a desktop browser, use the built-in Homebridge web interface:

    1. Open the Homebridge address in your browser (default port `8581`, for example `http://homebridge.local:8581`).
    2. Click the **Plugins** tab in the top navigation bar.
    3. Enter the device name or manufacturer into the search box.
    4. Click **Install** on the matching result.
    5. The browser terminal window downloads the npm package to your server.
    6. Once finished, the configuration window opens. Fill in your device details.
    7. Check the box for **Enable as Child Bridge** and click **Save**.
    8. Restart the bridge using the button in the dialog.
  </Tab>

  <Tab>
    ### Manual Installation via the Terminal [#manual-installation-via-the-terminal]

    On Linux servers, Raspberry Pi, or macOS, you can manage plugins through the command line:

    ```bash title="Install plugin globally with npm"
    # Standard npm installation:
    npm install -g homebridge-hue

    # Or if you use the Homebridge service manager:
    hb-service add homebridge-hue
    ```

    After installing the package, manually add its configuration block to `/var/lib/homebridge/config.json` (or your custom instance directory):

    ```json title="Example configuration block in config.json"
    {
      "platforms": [
        {
          "platform": "Hue",
          "name": "Philips Hue",
          "users": {
            "001788FFFE123456": "YourApiKeyHere"
          }
        }
      ]
    }
    ```

    Validate your JSON formatting to avoid syntax errors, then restart the service:

    ```bash title="Restart Homebridge"
    hb-service restart
    # Or through systemd:
    sudo systemctl restart homebridge
    ```
  </Tab>
</Tabs>

***

## Compatibility Checks Before Installation [#compatibility-checks-before-installation]

Every plugin defines required versions for Node.js and the Homebridge core in its `package.json` file.

<div className="flex flex-col md:flex-row gap-6 my-6 items-start">
  <div className="w-full md:w-1/2">
    <p className="text-fd-muted-foreground leading-relaxed">
      Upgrading to newer Node.js releases (like Node 22 or 24) or to Homebridge v2.x can break older plugins that depend on legacy C++ build utilities (such as 

      <code>node-gyp</code>

      ) that no longer compile.
    </p>

    <p className="text-fd-muted-foreground leading-relaxed mt-3">
      Homemanager automatically compares a plugin's system rules against your active server before installation starts. If a version requirement does not match, the app displays a warning with the exact version rules. This catches incompatibilities early and stops broken packages from halting your server. For detailed guidance on managing runtimes, see our guide on 

      <a href="/guide/updating-system-software" className="underline underline-offset-2 text-fd-foreground hover:text-fd-primary">Node.js and system updates</a>

      .
    </p>
  </div>

  <div className="w-full md:w-1/2 flex justify-center">
    <ImageZoom src="/images/homebridge/plugins/homemanager-compatibility-check.png" alt="Compatibility check in Homemanager for Homebridge and Node.js" className="max-w-[260px] rounded-2xl border border-fd-border shadow-md" caption="Automatic verification of Homebridge and Node.js version rules" />
  </div>
</div>

***

## Quality Criteria: How to Spot Reliable Plugins [#quality-criteria-how-to-spot-reliable-plugins]

To keep your smart home running consistently, check a plugin's maintenance status before installing. Beyond official verification, public project data on npm and GitHub helps you choose dependable extensions.

### The Official Verified Badge [#the-official-verified-badge]

The Homebridge developer team tests extensions against defined technical requirements and awards the **Verified** badge to qualifying projects:

* **Visual configuration:** It includes a `config.schema.json`, so settings can be changed in the user interface without modifying JSON files directly.
* **Child Bridge support:** The extension supports process isolation.
* **Node.js LTS support:** The package runs on current LTS releases and avoids deprecated APIs.
* **Crash protection:** It catches connection timeouts and network errors so an issue with one device does not crash Homebridge.
* **No telemetry:** The code does not track usage or send analytics data to external servers.

<Callout type="tip">
  Choose verified plugins whenever they are available for your hardware. They reduce setup errors and run more predictably over time.
</Callout>

### Checklist for Community Plugins Without a Badge [#checklist-for-community-plugins-without-a-badge]

When hardware requires an unverified community plugin, evaluate these indicators on GitHub and npm:

1. **Maintenance history:** The repository received its last release or commit within the past twelve months.
2. **Weekly downloads:** Steady download counts on npm indicate regular use across many installations.
3. **Repository issues:** Review the *Issues* tab on GitHub to see whether bug reports receive responses and timely fixes from the maintainer.
4. **Local network protocols:** Plugins that communicate directly over your home network (LAN, CoAP, or MQTT) respond faster and continue working during internet outages.

***

## Architecture: Platform vs. Accessory Plugins [#architecture-platform-vs-accessory-plugins]

Homebridge organizes extensions into two core types. This distinction determines how you configure the plugin and how devices appear in Apple Home.

### Platform Plugins [#platform-plugins]

Platforms power most modern smart home integrations. A platform plugin connects to an entire bridge system (such as the Philips Hue Bridge) or a manufacturer cloud account (such as Shelly or Ring) and automatically publishes all discovered accessories to Apple Home.

When you add a new bulb or sensor in the manufacturer's app later, the platform plugin detects it automatically during runtime. In `config.json`, platforms reside inside the `"platforms": [...]` array.

### Accessory Plugins [#accessory-plugins]

Accessory plugins control a single, dedicated device. Common examples include dummy switches for advanced Apple Home automations, HTTP relays, or wake-on-LAN triggers for desktop computers. Each accessory requires its own entry in the `"accessories": [...]` array of your configuration file.

***

## Child Bridges: Why Process Isolation Should Be the Default [#child-bridges-why-process-isolation-should-be-the-default]

Regardless of which installation path you take, configure each new plugin as a **Child Bridge**. For detailed setup instructions, read our full [Child Bridges guide](/guide/child-bridges).

In standard setups, plugins run within a single main process. If a network error causes one plugin to fail, the entire Homebridge server stops, taking all connected accessories offline.

Running a plugin in an isolated Child Bridge:

* Spawns a dedicated system process for that extension.
* Keeps all other accessories online if one integration fails.
* Isolates resource-heavy operations, such as camera live streams, from the core bridge.
* Allows you to restart an individual plugin in one or two seconds without interrupting the rest of your home.

***

## Related Guides [#related-guides]

<Cards>
  <Card icon="<Layers />" title="Setting Up Child Bridges" description="Step-by-step instructions on isolating plugins and pairing individual QR codes in Apple Home." href="/guide/child-bridges" />

  <Card icon="<Bug />" title="Fixing Startup Errors" description="How to resolve boot loops, port conflicts, and crashing plugins using server logs." href="/guide/troubleshooting-startup-errors" />

  <Card icon="<AlertTriangle />" title="Accessories Not Responding?" description="Common causes and fixes when accessories show 'No Response' after plugin configuration." href="/guide/troubleshooting-no-response" />
</Cards>