Homebridge Docker
Official Docker image for Homebridge - Emulate the iOS HomeKit API on your network
📢 Important Update
We have migrated the official Homebridge Docker image from oznu/homebridge to homebridge/homebridge.
Please update your configurations to use the new image location for the latest updates and features.
🚀 Quick Start
Prerequisites
- Docker Engine with networking access
- Host network mode support (required for HomeKit)
⚠️ Compatibility Note: This image does not work with Docker Desktop for Mac or Windows due to networking limitations (details).
📦 Available Images
This is a multi-architecture image supporting x86_64 and ARM64v8 platforms, plus ARM32v7 on images not yet moved to Ubuntu 26.04 (see below). Images are built on Ubuntu 26.04 or 24.04 depending on the release stream, and Ubuntu 22.04 for synology.
Ubuntu 26.04 rollout and 32-bit ARM: During fall 2026, every Homebridge Docker image except synology moves to Ubuntu 26.04, one release stream at a time. Node.js no longer publishes 32-bit builds, so images based on Ubuntu 26.04 no longer include the arm32v7 (32-bit ARM) architecture. If you run Homebridge in Docker on a 32-bit ARM device, move to a 64-bit (arm64v8) OS to keep receiving updates. Images already published stay available under their dated tags (for example 2026-10-23).
| Image Tag | Architectures | Release Type |
|---|
latest, ubuntu | amd64, arm32v7*, arm64v8 | Stable |
synology | amd64, arm32v7, arm64v8 | Stable |
beta | amd64, arm32v7*, arm64v8 | Beta |
alpha | amd64, arm64v8 | Alpha |
legacy | amd64, arm32v7*, arm64v8 | Legacy |
* arm32v7 is dropped when that release stream moves to Ubuntu 26.04. synology stays on Ubuntu 22.04 and is not part of this rollout.
🛠️ Installation
Using Docker Compose (Recommended)
Create a docker-compose.yml file:
services:
homebridge:
image: homebridge/homebridge:latest
restart: always
network_mode: host
hostname: docker-desktop # Optional: Set container hostname
volumes:
- ./volumes/homebridge:/homebridge
environment:
- TZ=America/Toronto # Optional: Set your timezone
- ENABLE_AVAHI=1 # Optional: Enable/disable Avahi (1=enabled, 0=disabled)
logging:
driver: json-file
options:
max-size: '10m'
max-file: '1'
healthcheck:
test: ["CMD-SHELL", "curl --fail http://localhost:8581 || exit 1"]
interval: 60s
retries: 5
start_period: 300s
timeout: 2s
Start the container:
docker compose up -d
Using Docker CLI
docker run \
--net=host \
--name=homebridge \
-e TZ=America/Toronto \
-v $(pwd)/homebridge:/homebridge \
homebridge/homebridge:latest
⚙️ Configuration
Required Parameters
| Parameter | Docker Compose | Docker CLI | Description |
|---|
| Network Mode | network_mode: host | --net=host | Required - Enables host networking for HomeKit discovery |
| Volume Mount | volumes: | -v /path:/homebridge | Required - Persistent storage for config and plugins |
Optional Parameters
| Parameter | Docker Compose | Docker CLI | Default | Description |
|---|
| Hostname | hostname: homebridge | --hostname=homebridge | Container ID | Set custom hostname for the container |
| Timezone | environment:- TZ=America/Toronto | -e TZ=America/Toronto | UTC | Set timezone (list) |
| Avahi mDNS | environment:- ENABLE_AVAHI=1 | -e ENABLE_AVAHI=1 | 1 | Set to 0 to disable Avahi mDNS service |
Note: When running with ENABLE_AVAHI=0, you can mount the host's mDNS service to enable mDNS usage in the container:
volumes:
- ./volumes/homebridge:/homebridge
- /var/run/dbus:/var/run/dbus # Mount host D-Bus socket
- /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket # Mount host Avahi socket
🖥️ Homebridge UI
Access the Homebridge UI at http://<your-server-ip>:8581
The UI allows you to:
- ✅ Install, update, and remove plugins
- ✅ Edit Homebridge configuration
- ✅ View logs and restart Homebridge
- ✅ Manage accessories and bridges
🔧 Custom Startup Script
For advanced customization, use the Startup Script feature in the UI (Settings → Startup & Environment).
The startup.sh script:
- Runs on every container start
- Persists across container recreations
- Can install packages, copy files, or execute custom commands
Example:
#!/bin/sh
# Install custom Node.js packages
npm install -g some-custom-package
# Install Python dependencies
pip3 install some-python-library
# Copy configuration from host
cp /homebridge/custom-config.json /etc/custom-config.json
📚 Step-by-Step Guides
🔄 Updates
Manual Updates
Pull the latest image and recreate your container:
docker compose pull
docker compose up -d
Automated Updates
⚠️ Not Recommended: Automated updates using tools like Watchtower are strongly discouraged and done at your own risk
In-Container Updates
Since the 2025-06-25 release, updates to
- Homebridge core
- Homebridge UI
- Node.js runtime
will be overwritten if the container is updated.
🎥 FFmpeg Support
This image includes FFmpeg with libfdk-aac audio support for camera streaming and video processing.
✅ Container Validation
This repository includes automated validation to ensure container builds work correctly.
Manual Validation
To validate a specific release:
- Go to Actions
- Select "Validate Docker Container"
- Click "Run workflow"
- Choose the release tag:
latest - Stable releasebeta - Beta pre-releasealpha - Alpha early release
The validation workflow will:
- ✅ Start the container and verify it runs
- ✅ Check Homebridge UI accessibility on port 8581
- ✅ Verify Homebridge service starts with version detection
- ✅ Validate container health checks
- ✅ Extract and validate the Docker manifest
🐛 Troubleshooting
1. FFmpeg Issues
FFmpeg with libfdk-aac audio support is included in this image. No additional installation required.
2. Container Won't Start on Older Raspbian
If you see errors like:
Node.js[445]: ../src/util.cc:188:double node::GetCurrentTimeInMicroseconds(): Assertion `(0) == (uv_gettimeofday(&tv))' failed.
s6-svscan: warning: unable to iopause: Operation not permitted
Your host OS needs to be updated. See #434 and #441 for solutions.
3. Get Help on Discord
Join the Official Homebridge Discord and ask in the #docker channel.
📄 License
Copyright (C) 2024 homebridge
Copyright (C) 2017-2022 oznu
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Made with ❤️ by the Homebridge community
