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

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗