Abstract violet and amber illustration representing Zigbee2MQTT, a bridge that converts Zigbee mesh network traffic into MQTT messages

Zigbee2MQTT

Zigbee2MQTT

Zigbee2MQTT is a bridge, not a hub. It takes the radio traffic from your Zigbee devices — lights, sensors, plugs, buttons — and turns it into MQTT messages that any home automation platform can subscribe to. It replaces the vendor’s proprietary Zigbee gateway (Ikea’s Trådfri hub, Philips Hue’s bridge, Aqara’s hub) with a single piece of software you control, running on hardware you own.

That distinction matters. Zigbee2MQTT gets listed next to Home Assistant as a "smart home platform" more often than it should, and it isn’t one. It has no automation engine and no real dashboard beyond device pairing and configuration. What it has is a web UI for pairing devices, and an MQTT connection that pushes every state change out to whatever is listening: Home Assistant, openHAB, Node-RED, or a script you wrote yourself.

What Zigbee2MQTT actually does

Every Zigbee network needs a coordinator: a radio that talks directly to your bulbs and sensors over the 802.15.4 protocol. Vendor hubs bundle this coordinator with a cloud-connected app. Zigbee2MQTT does the same job locally. It drives a USB Zigbee coordinator (commonly a Texas Instruments CC2652-based dongle like the Sonoff Zigbee 3.0 USB Dongle Plus, or a ConBee II/III from Phoscon), keeps a live map of every paired device, and republishes state changes as MQTT topics, such as zigbee2mqtt/living-room-motion/state.

The project splits its internals across three separate GitHub repositories, by its own documentation. zigbee-herdsman handles low-level radio communication with the coordinator hardware, zigbee-herdsman-converters maps hundreds of vendor-specific device quirks to a common data model, and Zigbee2MQTT itself drives the stack and serves the web frontend. That converters library is a big part of why Zigbee2MQTT tends to support new devices faster than closed vendor hubs — support gets added by the community, in the open, without waiting on a vendor firmware update.

Zigbee2MQTT vs. Home Assistant’s built-in ZHA

Home Assistant ships its own Zigbee integration, ZHA (Zigbee Home Automation), which talks to the same coordinator hardware directly, with no MQTT broker or extra service in between. This is the comparison people actually search for, and the honest answer is that both work. The difference is architectural, not a feature gap.

ZHA is simpler if Home Assistant is the only system that will ever consume your Zigbee data: one less service to run, one less thing to keep updated. Zigbee2MQTT becomes the better choice the moment more than one system needs the same Zigbee data. It plays natively with openHAB, Domoticz, Gladys Assistant, Homey, and ioBroker, and it keeps working even if you migrate away from Home Assistant later, because your devices are speaking a vendor-neutral protocol instead of being locked into one platform’s integration layer.

Installing Zigbee2MQTT with Docker

The official Docker image is the fastest path to a working setup. Mount a data directory for the device database and configuration file, pass through the USB coordinator, and point the container at an MQTT broker:

docker run -d --name zigbee2mqtt \
  --device=/dev/ttyUSB0 \
  -v /path/to/zigbee2mqtt/data:/app/data \
  -p 8080:8080 \
  -e TZ=Europe/Paris \
  koenkk/zigbee2mqtt

That last part isn’t optional. Zigbee2MQTT doesn’t talk to Home Assistant or anything else directly. It only speaks MQTT, which means it needs a broker like Mosquitto running before it has anywhere to publish. That pairing is common enough that most self-hosted Zigbee setups run both containers side by side on the same Docker network.

Common setup issues

A few problems come up often enough to mention. The USB coordinator needs to be passed through to the container explicitly, and a stable /dev/serial/by-id/... path survives reboots better than a raw /dev/ttyUSB0 number that can shift. Permission errors on that device are almost always a Docker user/group mismatch, not a hardware fault. The bundled web frontend runs on port 8080 by default and isn’t exposed outside the container unless you publish it explicitly. And a coordinator running outdated firmware is one of the more common causes of a network that pairs devices fine but drops them intermittently. Checking the recommended firmware version for your specific dongle before your first pairing session saves a lot of later troubleshooting.

License and governance

Zigbee2MQTT is licensed under GPL-3.0, confirmed directly from the LICENSE file in the Koenkk/zigbee2mqtt GitHub repository. Unlike Mosquitto or openHAB, it isn’t tied to a foundation. It’s maintained by Koenraad Vandenborne (Koenkk) and a large community of device-support contributors, funded through GitHub Sponsors and direct donations rather than corporate backing. That independence is part of why it moves fast: new device support ships as community pull requests, not roadmap items.

If you’re building a self-hosted smart home around Home Assistant, Zigbee2MQTT paired with Mosquitto as the broker is the most common way to get vendor-independent Zigbee support without depending on any single hub’s built-in integration. For the bigger picture of how the pieces fit together, see our guide to the self-hosted home automation stack.