Run Homebridge on Raspberry Pi: Complete Setup Guide

ByC Wilson Updated on
Run Homebridge on Raspberry Pi

Run Homebridge on Raspberry Pi to add non-HomeKit smart devices to Apple Home without replacing existing hardware. Homebridge is a Node.js server that emulates a HomeKit accessory hub. Plugins translate each device’s native API into HomeKit commands. The Homebridge Config UI runs in a browser on port 8581 and handles plugin installation, configuration, and log viewing without requiring command-line access after the initial setup.

Last tested: Raspberry Pi OS Bookworm Lite 64-bit | April 3, 2026 | Raspberry Pi 4 Model B (2GB) | Homebridge v1.8 | Node.js v22 LTS

Key Takeaways

  • Homebridge emulates a HomeKit hub and bridges non-HomeKit devices into Apple Home via plugins. It does not replace HomeKit. It extends it.
  • Use the official Homebridge Debian package rather than npm install -g. The package handles Node.js installation, the systemd service, and updates through apt.
  • Pi 4 is recommended for multiple plugins or high plugin counts. Pi Zero 2 W works for simple setups with fewer than ten accessories.
  • The config.json file is the core configuration. Back it up before every plugin update or configuration change. A syntax error in this file prevents Homebridge from starting.
  • Homebridge must be on the same network subnet as your iPhone for initial pairing. A guest network or VLAN will prevent HomeKit discovery.
  • Run Homebridge from USB SSD rather than microSD for long-term reliability. Node.js and plugins generate significant write activity.
Homebridge on Raspberry Pi architecture diagram showing non-HomeKit devices connected via plugins through Homebridge to Apple Home

What Homebridge Does

HomeKit only supports devices that have been certified by Apple. Homebridge works around this by presenting itself to Apple Home as a certified bridge accessory. Each plugin installed in Homebridge communicates with a specific device or service using its native protocol (local API, cloud API, MQTT, or Z-Wave) and translates commands and state changes into the HomeKit accessory format that Apple Home understands.

From Apple Home’s perspective, the devices appear as native HomeKit accessories. They appear in automations, respond to Siri, and work with the Home app on iPhone, iPad, Mac, and Apple Watch. The Homebridge layer is invisible to Apple Home once pairing is complete.

Homebridge vs Home Assistant

FeatureHomebridgeHome Assistant
Primary purposeBridge devices into Apple HomeStandalone automation platform
InterfaceApple Home appHome Assistant dashboard
Setup complexityLowMedium to high
Plugin ecosystem2,000+ HomeKit plugins3,000+ integrations
Apple Home dependencyRequiredOptional (via HomeKit integration)
Resource useLow (Node.js)Higher (Python, database)

Both can run simultaneously on the same Pi. Home Assistant can also expose its own devices to HomeKit via its built-in HomeKit Bridge integration, making the two complementary rather than competing for most users.

Hardware Requirements

ComponentMinimumRecommended
Raspberry PiPi Zero 2 WPi 4 (2GB+)
Storage16GB microSDUSB SSD
Power supply5V/2.5AOfficial Pi 4 adapter (5V/3A)
NetworkWi-FiGigabit Ethernet

Storage write load is the main reason to prefer USB SSD. Node.js package management, plugin updates, and Homebridge’s internal state writes are persistent. A high-endurance microSD extends life significantly if SSD is not an option. See Booting Raspberry Pi from USB SSD and Preventing SD Card Corruption on Raspberry Pi.

Step 1: Prepare Raspberry Pi OS

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. In the advanced settings, configure hostname, enable SSH, set credentials, and add Wi-Fi if needed. Assign a static IP via your router’s DHCP reservation. After first boot:

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Expected result: SSH connects reliably to the same IP address after reboot.

Step 2: Run Homebridge on Raspberry Pi

The official Homebridge Debian package is the recommended installation method. It installs Node.js at the correct version, creates the Homebridge systemd service, and enables updates through apt. This is preferable to a manual npm install -g which requires separate Node.js version management and manual service setup.

# Add the Homebridge apt repository
curl -sSfL https://repo.homebridge.io/KEY.gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/homebridge.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/homebridge.gpg] https://repo.homebridge.io stable main" | sudo tee /etc/apt/sources.list.d/homebridge.list > /dev/null

sudo apt update
sudo apt install homebridge -y

The installer sets up Homebridge as a systemd service that starts automatically on boot. It also installs the Homebridge Config UI X web interface.

Expected result: sudo systemctl status homebridge shows the service as active and running. The install output shows a QR code and pairing PIN for HomeKit.

Step 3: Access the Homebridge UI

Open a browser on any device on the same network and navigate to:

http://<pi-ip-address>:8581

The default credentials are admin / admin. Change the password immediately after first login. The UI dashboard shows Homebridge status, installed plugins, recent logs, and system resource usage.

Expected result: The Homebridge UI loads in the browser. The status indicator shows Homebridge as running. A HomeKit pairing QR code is visible in the UI.

Step 4: Pair with Apple Home

Open the Home app on iPhone or iPad. Tap the + icon, then Add Accessory. Scan the QR code shown in the Homebridge UI, or tap “More options” and enter the 8-digit PIN manually. Homebridge will appear as a bridge accessory in the Home app.

If the QR code scan fails or the accessory is not found, confirm that the iPhone and Pi are on the same network subnet. A guest Wi-Fi network, VLAN separation, or mDNS blocking between subnets will prevent HomeKit discovery. The Pi must be reachable by mDNS (hostname.local) from the iPhone for pairing to complete.

Expected result: Homebridge appears as a bridge in the Home app. Any accessories already configured in plugins appear as devices in the Home app.

Step 5: Install Plugins and Add Devices

Finding plugins

In the Homebridge UI, go to the Plugins tab and search by device brand or model. The search queries the npm registry for packages with the homebridge-plugin keyword. Over 2,000 plugins are available covering smart lights, plugs, thermostats, locks, cameras, garage doors, and more. Common well-maintained plugins include:

  • homebridge-tplink-smarthome: TP-Link Kasa smart plugs and bulbs
  • homebridge-govee: Govee smart lights
  • homebridge-nest: Google Nest thermostats
  • homebridge-ring: Ring doorbells and cameras
  • homebridge-mqtt-thing: generic MQTT devices
  • homebridge-z2m: Zigbee devices via Zigbee2MQTT

Configuring a plugin

After installing a plugin, click its settings icon in the Plugins tab. Most plugins provide a configuration form in the UI. For plugins that require manual JSON configuration, the changes are written to config.json under the platforms or accessories array. Always back up config.json before editing manually. A JSON syntax error such as a missing comma or mismatched bracket prevents Homebridge from starting.

# Back up config.json before manual edits
cp ~/.homebridge/config.json ~/.homebridge/config.json.bak

# Validate JSON syntax
python3 -m json.tool ~/.homebridge/config.json

After configuring a plugin, restart Homebridge from the UI or with:

sudo systemctl restart homebridge

Expected result: After restart, the new accessories appear in the Home app under the Homebridge bridge. If they do not appear, check the Homebridge logs in the UI for plugin-specific errors.

Managing config.json

The config.json file lives at /var/lib/homebridge/config.json (package install) or ~/.homebridge/config.json (manual install). It contains Homebridge’s bridge settings, platform plugins, and accessory plugins. A minimal example:

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    },
    "platforms": [
        {
            "platform": "HomebridgeConfigUi",
            "title": "Config UI X",
            "port": 8581
        }
    ]
}

Each plugin installed via the UI adds its own block to the platforms array. Do not duplicate platform entries. Homebridge will fail to start if the same platform is registered twice. Use the built-in JSON editor in the Homebridge UI rather than editing the file directly where possible.

Automations and Siri

Once devices appear in the Home app, they participate in HomeKit automations and Siri commands without additional configuration. Set up scenes (groups of device states) and automations (time-based or trigger-based) directly in the Home app. Siri responds to accessory names as defined in the Home app. Rename accessories to natural phrases for more reliable voice control.

Homebridge accessories behave identically to native HomeKit devices in automations. A Govee light brought in via Homebridge can trigger a Hue light (native HomeKit), and vice versa. The Home app does not distinguish between native and bridged accessories in automation logic.

Maintenance

Update Homebridge and plugins

# Update Homebridge package
sudo apt update && sudo apt upgrade homebridge -y

# Update all plugins via UI, or via npm:
sudo npm update -g homebridge homebridge-config-ui-x

Plugin updates are managed in the Homebridge UI. A notification badge appears when updates are available. Update plugins individually rather than all at once so that a breaking change in one plugin is easier to identify and roll back.

Back up configuration

The Homebridge UI has a built-in backup feature under Settings. It exports a .tar.gz archive containing config.json, plugin data, and accessory cache. Download a backup after any significant configuration change. The backup can be restored via the same Settings menu, which simplifies migration to a new Pi or recovery after storage failure.

Monitor resource usage

# Check Homebridge service status and memory
sudo systemctl status homebridge

# Monitor system resources
htop

# Check temperature and throttling
vcgencmd measure_temp
vcgencmd get_throttled

Memory usage grows with the number of plugins and accessories. A Pi 4 with 2GB handles typical setups of 20 to 50 accessories without issue. If memory becomes a constraint, see Setting Up zram on Raspberry Pi for increasing effective memory through compression.

Expanding the Setup

Zigbee and Z-Wave

Homebridge does not communicate with Zigbee or Z-Wave radios directly. The standard approach is to run Zigbee2MQTT alongside Homebridge on the same Pi with a USB Zigbee coordinator (such as the Sonoff Zigbee 3.0 USB Dongle Plus). Zigbee2MQTT exposes devices over MQTT, and the homebridge-z2m plugin bridges those into HomeKit.

Running alongside Home Assistant

Homebridge and Home Assistant can run on the same Pi. Home Assistant’s built-in HomeKit Bridge integration overlaps with Homebridge’s purpose for Home Assistant devices, so the typical setup is to use Homebridge for devices that Home Assistant does not support well, and Home Assistant’s native HomeKit Bridge for everything else. For a full Home Assistant install on the Pi, see Home Assistant on Raspberry Pi 5.

Security

Change the Homebridge UI admin password immediately after first login. The default admin/admin credentials are well known. Use a strong SSH password or key-based authentication on the Pi. If accessing Homebridge remotely, use Tailscale or ZeroTier rather than exposing port 8581 to the internet. Homebridge runs entirely locally and does not require any open inbound ports for normal operation.

Plugins that use cloud APIs (Ring, Nest, Ecobee) require credentials stored in config.json. Treat this file as sensitive. Do not commit it to a public repository and ensure the Homebridge backup archive is stored securely.

Troubleshooting

Homebridge fails to start

# Check service logs for the error
sudo journalctl -u homebridge -n 50

# Validate config.json syntax
python3 -m json.tool /var/lib/homebridge/config.json

The most common cause is a JSON syntax error in config.json. Run the Python validator. It will identify the the exact line number with the error. Restore from backup if the error is not immediately obvious.

Accessories not appearing in Home app

Check the Homebridge logs in the UI for plugin errors. Confirm the plugin is configured correctly and that any required API tokens or local IPs are current. If the plugin shows no errors but devices still do not appear, remove and re-add the Homebridge bridge in the Home app and re-pair.

HomeKit pairing fails

Confirm the iPhone and Pi are on the same network subnet with no VLAN separation. Disable any VPN on the iPhone during initial pairing. If pairing still fails, reset the Homebridge accessory cache from the UI under Settings, restart Homebridge, and try again.

Plugin fails to load or crashes

Check the plugin’s GitHub page for the required Node.js version. If the installed Node.js version does not match, install the correct version with nvm. Alternatively, the Homebridge package install manages Node.js versions automatically through apt, which avoids this issue entirely.

FAQ

Can I use a Raspberry Pi Zero for Homebridge?

The Pi Zero 2 W works for basic setups with a small number of plugins. The original Pi Zero (not Zero 2) is too slow for practical use. For setups with more than ten accessories or several active plugins, Pi 4 provides significantly more headroom.

Does Homebridge require jailbreaking or modifying Apple devices?

No. Homebridge operates entirely within Apple’s HomeKit accessory protocol. It presents itself to Apple Home as a certified bridge, which is a supported mechanism. No modification to any Apple device is required.

Is Homebridge legal?

Yes. Homebridge is open-source software licensed under Apache 2.0. It implements Apple’s published HomeKit Accessory Protocol. Using it does not violate Apple’s terms of service.

Does Homebridge replace Apple HomeKit?

No. Homebridge extends HomeKit by adding compatibility for devices that Apple has not certified. Apple Home remains the control interface. Homebridge is invisible to the user once pairing is complete. All control happens through the standard Home app.

Can I control Homebridge devices when away from home?

Yes, with an Apple Home hub on your network. An Apple TV 4K, HomePod, or HomePod mini acts as the remote access relay for HomeKit. Without a hub, HomeKit only works on the local network. The hub does not need to be on the same subnet as the Pi, only on the same iCloud account.

References

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (2GB). Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. Homebridge v1.8, Node.js v22 LTS.

Was this helpful?

Yes
No
Thanks for your feedback!