Homebridge Docker: the official image, host networking and what it will not do

What the official Homebridge image replaces

Homebridge emulates the iOS HomeKit API on your network so that non-HomeKit devices appear in the Home app. Running it directly on a host means managing Node.js, a service manager, and a media stack for camera accessories yourself. This repository is the packaging layer: it publishes homebridge/homebridge on Docker Hub with the Homebridge core, the Homebridge UI, and FFmpeg built with libfdk-aac for camera streaming.

The audience is narrow and specific. You already run Docker on a Linux box, a Raspberry Pi or a NAS, and you want Homebridge treated like any other container: a volume for state, a restart policy, an image tag you can roll back. The README also carries a migration note that matters more than any feature: the official image moved from oznu/homebridge to homebridge/homebridge, and existing configurations need to point at the new location.

Host networking is the whole architecture

HomeKit discovery runs over mDNS, and mDNS does not survive a bridged Docker network. That single constraint explains the image's design. The README lists network_mode: host (or --net=host) as required, not recommended, because the container has to answer discovery traffic on the same network interfaces as the host.

The build is a multi-stage arrangement rather than a single script. The Dockerfile starts from ubuntu:${BASE_IMAGE}, with 24.04 as the default and 22.04 reserved for the synology tag, and installs s6-overlay 3.2.0.2 as the process supervisor. The package.json in the repository is a stub: it pins @homebridge/homebridge-apt-pkg at 2.0.18 and ffmpeg-for-homebridge at 2.2.2 to track the versions used by the stable release stream. Five tag families come out of this: latest and ubuntu on Ubuntu 24.04, legacy for Homebridge 1.x, synology on Ubuntu 22.04, and beta and alpha for pre-release testing. All of them are published for amd64, arm32v7 and arm64v8.

Avahi is the other moving part. ENABLE_AVAHI defaults to 1, and the README documents setting it to 0 when you would rather use the host's mDNS daemon, in which case you mount /var/run/dbus and /var/run/avahi-daemon/socket into the container.

Installing Homebridge in Docker with Compose

The README recommends Docker Compose. Create a docker-compose.yml with the service below, then run docker compose up -d from the same directory. The image tag, the host network mode and the /homebridge volume are the three lines that matter; TZ is optional and defaults to UTC.

services:
  homebridge:
    image: homebridge/homebridge:latest
    restart: always
    network_mode: host
    volumes:
      - ./volumes/homebridge:/homebridge
    environment:
      - TZ=America/Toronto
      - ENABLE_AVAHI=1

docker compose up -d

Once the container is up, open http://<your-server-ip>:8581 in a browser. That port is the Homebridge UI, and the README's healthcheck example curls http://localhost:8581 to decide whether the container is alive. From the UI you install and remove plugins, edit the Homebridge configuration, read logs, restart Homebridge, and manage accessories and bridges.

The Docker CLI equivalent is a single command, useful when you want to see the container before committing to a Compose file:

docker run \
  --net=host \
  --name=homebridge \
  -e TZ=America/Toronto \
  -v $(pwd)/homebridge:/homebridge \
  homebridge/homebridge:latest

For anything that has to happen on every boot, the UI exposes a Startup Script under Settings, then Startup & Environment. The README says startup.sh runs on every container start and persists across container recreations, and its example installs an npm package globally and a Python package with pip3.

Docker Desktop on Mac and Windows is out

The README states plainly that the image does not work with Docker Desktop for Mac or Windows because of networking limitations, and links issue 570 for the details. This is not a configuration problem you can work around by changing a flag. Host networking on those platforms does not give the container the same network identity as the host, and HomeKit discovery depends on exactly that. If your plan was to run this on a laptop for testing and move it to a Pi later, the laptop half of that plan does not exist. Use a Linux host or the Pi from the start.

The second limitation is update behaviour. Since the 2025-06-25 release, updates to Homebridge core, the Homebridge UI and the Node.js runtime inside the container are overwritten when the container image is updated. In-container upgrades do not survive. Treat the image tag as the unit of versioning and update by pulling a new image.

The README also discourages automated updates through tools like Watchtower, calling them strongly discouraged and done at your own risk. A Homebridge container that restarts into a broken plugin takes your HomeKit accessories with it, and there is no rollback procedure documented in the README.

Updating, and what the tags cost you

Manual updates are two commands. The README gives them without qualification:

docker compose pull
docker compose up -d

Tag choice is where the maintenance cost actually sits. latest, ubuntu and synology track stable releases. legacy holds Homebridge 1.x, which is the tag to use if a plugin you depend on has not moved to 2.x. beta and alpha ship pre-release Homebridge versions for testing, and the release list shows how fast those move: beta-2026-09-24, alpha-2026-09-24 and beta-2026-09-22 are three separate builds inside three days. Pinning beta on a production bridge means pulling a new image every couple of days or falling behind deliberately.

The repository's last push was on 2026-09-24, and it is not archived. The project publishes alpha and beta streams continuously, which is a signal about how the image is maintained rather than about any individual build being safe to run.

The licence is GPL-3.0, and the Dockerfile labels the image with org.opencontainers.image.licenses="GPL-3.0". That is a copyleft licence, which matters if you plan to redistribute a modified image or bake it into a product; if you are only running the container on your own hardware, the practical effect is different. This is a description of the licence, not legal advice, and anyone redistributing should read the terms themselves.

Home Assistant versus Homebridge in a container

The comparison people actually make is Home Assistant, and the difference is architectural rather than a matter of features. Home Assistant is a full home automation platform with its own dashboards, automations and integrations, and it can bridge devices to HomeKit through its HomeKit Bridge integration. Homebridge does one job: it exposes accessories and plugins to HomeKit. It has no automation engine of its own, and Apple's Home app is the interface.

That makes the choice about where your logic lives. If you want automations, dashboards and a device database in one system, Home Assistant is the container to run, and adding a HomeKit bridge to it is a configuration step inside that system. If HomeKit is the interface you want and your automations belong in the Home app or in Shortcuts, this image gives you a smaller surface: a config volume, a UI on 8581, and FFmpeg for cameras. The cost of the smaller surface is that anything Home Assistant does natively, Homebridge needs a plugin for, and plugin quality is outside this repository's control.

Editorial conclusion

Adopt this image if you run Homebridge on a Linux host, a Raspberry Pi or a NAS with host networking available, and you want the official build with FFmpeg plus libfdk-aac already inside. Do not adopt it if your only Docker host is Docker Desktop for Mac or Windows, because the README states the image does not work there. Before you migrate, verify two things: that your current setup still points at oznu/homebridge, since the project moved to homebridge/homebridge, and that you have pinned a tag rather than relying on in-container updates, which the release notes say are overwritten when the container is updated.

Frequently asked questions

Official sources

1. homebridge/docker-homebridge on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases