Zigbee2MQTT: Zigbee to MQTT Bridge Without a Vendor Gateway
Zigbee 🐝 to MQTT bridge 🌉, get rid of your proprietary Zigbee bridges 🔨
At a glance
- What is it?
- Zigbee2MQTT replaces proprietary Zigbee hubs with a TypeScript bridge that publishes device events to MQTT. It is a strong fit for Home Assistant users with a supported coordinator, and a poor fit for anyone who wants a self-contained appliance.
- Who is it for?
- Adopt Zigbee2MQTT if you run Home Assistant, Domoticz, ioBroker, Homey or Gladys Assistant, already have an MQTT broker, and are willing to check the supported-devices list before buying hardware. Do not adopt it if you want a sealed appliance with vendor support, or if you cannot run a Node.js process with a USB coordinator attached.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 29, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The vendor bridge problem Zigbee2MQTT removes
Zigbee devices normally arrive paired to a hub from the same brand: a Philips Hue Bridge for Hue bulbs, an Ikea gateway for Tradfri, a Xiaomi gateway for sensors. Those bridges decide which devices you may pair, which firmware you receive, and which automation systems can read the data. If you own devices from three vendors, you end up with three hubs and three apps.
Zigbee2MQTT sits between a generic Zigbee coordinator and your automation software. The README states its purpose plainly: it "allows you to use your Zigbee devices without the vendor's bridge or gateway." Instead of a per-vendor API, every device becomes a set of MQTT topics, and MQTT is a protocol almost every home automation platform already speaks.
The audience is therefore narrower than "smart home users". It is people who already run a broker and an automation engine, who are comfortable with YAML and a Linux service, and who want devices from Xiaomi, IKEA, Philips and OSRAM on one network. If you have never administered a Linux host, the setup cost is real, and the documentation's own getting-started page warns readers not to skip sections on a first visit.
Three modules, one JSON database, and MQTT at the top
The architecture is split across three repositories, and the README describes the stack from the hardware upward. zigbee-herdsman talks to the adapter itself; for Texas Instruments hardware it uses the TI zStack monitoring and test API. zigbee-herdsman exposes an API to the layer above.
zigbee-herdsman-converters maps individual device models to the Zigbee clusters they support. Clusters are the part of the Zigbee specification that defines how lights, sensors and switches exchange data. This is where per-model quirks live, which is why device support is a list rather than a promise.
Zigbee2MQTT itself drives zigbee-herdsman and translates Zigbee messages into MQTT messages. It also keeps state in a database.db file, described in the README as a text file holding a JSON database of connected devices and their capabilities. That file matters operationally: it is the record of what has been paired, and it is the thing you back up before a migration.
On top of that, the project ships web interfaces. The README names zigbee2mqtt-frontend and zigbee2mqtt-windfront as separate projects providing monitoring and configuration. The MQTT layer is what makes the design portable: Home Assistant, Homey, Domoticz, Gladys Assistant and ioBroker all have integrations, and the README calls out Home Assistant OS with the official addon as a supported path.
Installing Zigbee2MQTT and pairing a first device
The README does not inline install commands; it points to the getting-started guide on zigbee2mqtt.io and to the supported-devices page for hardware checks. What the repository does show is how the project is built and started from source, and the package.json defines the runtime constraint.
The engines field requires Node.js ^22.2.0 || ^24 || <=26.2, and the declared package manager is pnpm 10.18.3. After cloning, the build step compiles the TypeScript in lib/ and writes a hash:
pnpm install --include=dev
pnpm run build
pnpm startpnpm start runs node index.js, which is also the main entry in package.json. For iterative work the README suggests pnpm run build:watch in a second terminal so changes in lib/ recompile as you edit. Before submitting changes it asks for pnpm run check:w followed by pnpm run test:coverage.
Configuration lives in a YAML file, and the getting-started guide is where the full schema is documented. The README and repository files given here do not include a sample configuration, so the example to follow is the one on zigbee2mqtt.io rather than anything reproduced in this article.
The zigbee2mqtt-frontend and zigbee2mqtt-windfront projects supply the web interfaces mentioned in the README, which is where you permit joining and watch devices appear. Supported devices are listed by vendor on zigbee2mqtt.io/supported-devices, and that page is the one to check before ordering hardware.
Where Zigbee2MQTT is the wrong tool
Device support is the first boundary. The README links to an extensive list rather than claiming universal compatibility, and the per-model mapping lives in zigbee-herdsman-converters. A device that is not in that mapping is not a device you can control, regardless of whether it is technically Zigbee-compliant. Buying first and checking later is the most common way to waste money here.
The second boundary is the coordinator. Zigbee2MQTT does not talk to every USB stick; the architecture description ties support to what zigbee-herdsman implements, naming Texas Instruments hardware as an example. The getting-started guide carries the authoritative list.
The third is operational. This is a Node.js service, not firmware on a sealed box. It needs a host that stays up, a broker, and a serial device that survives reboots. If you want a hub you can unplug, move to another room and forget about, a vendor bridge does that job better.
Finally, state lives in database.db. The README describes it as a JSON text file of connected devices and their capabilities. Anyone who deletes it loses the pairing record. There is no documented rollback procedure in the README for a bad upgrade, so the practical safeguard is copying database.db before you change versions.
Zigbee2MQTT versus ZHA
The comparison people ask about most is with ZHA, Home Assistant's built-in Zigbee integration. The difference is architectural, not cosmetic.
ZHA is a component inside Home Assistant. Devices appear as Home Assistant entities, and the integration is configured through the Home Assistant UI. There is no broker in the path, and nothing outside Home Assistant can consume the device state directly.
Zigbee2MQTT is an independent process that publishes to MQTT. Home Assistant is one consumer among several: the README lists Homey, Domoticz, Gladys Assistant and ioBroker as integrations, and Home Assistant OS can run it through the official addon. That indirection is the point. It also means one more moving part: if the broker is down, the devices are unreachable even though the coordinator is fine.
A practical consequence is that the two do not share a coordinator. Pairing a device in one and expecting the other to see it does not work, because each keeps its own state and its own view of the network. Choose one per coordinator.
Licence and the cost of staying current
Zigbee2MQTT is GPL-3.0. If you run it at home, the licence is not something you need to think about. If you embed it in a product you distribute, the copyleft terms apply to the combined work, and that is a question for a lawyer rather than a review. The three module split is worth noting for the same reason: zigbee-herdsman and zigbee-herdsman-converters are separate repositories, so their licences should be checked individually rather than assumed from this one.
Upgrade cost is mostly about device mappings. New device support arrives through zigbee-herdsman-converters, so a Zigbee2MQTT release can change how an existing device is exposed. The release history shows a steady cadence: 2.13.0 on 2026-08-01, 2.14.0 on 2026-09-01, and 2.14.1 on 2026-09-03. The repository's last push was on 2026-09-19, so this is a project that moves between releases.
That cadence is a maintenance commitment. Every upgrade is a chance that an entity name or a property changes, and the README does not document a rollback path. Copying database.db and pinning a version before upgrading is the cheap insurance.
Editorial conclusion
Adopt Zigbee2MQTT if you run Home Assistant, Domoticz, ioBroker, Homey or Gladys Assistant, already have an MQTT broker, and are willing to check the supported-devices list before buying hardware. Do not adopt it if you want a sealed appliance with vendor support, or if you cannot run a Node.js process with a USB coordinator attached. Before committing, verify three things: that your exact device model appears on the supported-devices page, that your coordinator is listed in the getting-started guide, and that your Node.js version satisfies the engines field, which is ^22.2.0 || ^24 || <=26.2.
Frequently asked questions
What is Zigbee2MQTT?
It is a bridge that lets you use Zigbee devices without the vendor's bridge or gateway, controlling them through MQTT. It is built from three modules: zigbee-herdsman for adapter communication, zigbee-herdsman-converters for per-model mapping, and Zigbee2MQTT itself for translating Zigbee messages into MQTT messages.
What is the difference between Zigbee and Zigbee2MQTT?
Zigbee is the wireless protocol that the devices and clusters use to talk to each other. Zigbee2MQTT is software that drives a Zigbee coordinator and republishes those device events as MQTT messages so an automation platform can consume them.
What are the limitations of Zigbee2MQTT?
Device support depends on whether the model is mapped in zigbee-herdsman-converters, and coordinator support depends on what zigbee-herdsman implements. It is also a Node.js service that needs a host, an MQTT broker and a serial coordinator, rather than a self-contained appliance.
How do I install Zigbee2MQTT?
The README points to the getting-started guide at zigbee2mqtt.io rather than inlining steps, and warns not to skip sections on a first visit. From a source checkout the documented path is pnpm install --include=dev, then pnpm run build, then pnpm start, on Node.js ^22.2.0 || ^24 || <=26.2.
How do I use Zigbee2MQTT with Home Assistant?
The README names Home Assistant OS with the official addon as a supported integration, and points to the Home Assistant integrations page for other installations. Because the bridge publishes over MQTT, Home Assistant consumes the device state from the broker.
How do I access the Zigbee2MQTT frontend?
The README states that Zigbee2MQTT provides several web-based interfaces through the zigbee2mqtt-frontend and zigbee2mqtt-windfront projects, which allow monitoring and configuration. The getting-started and frontend documentation on zigbee2mqtt.io covers how they are enabled.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/koenkk-zigbee2mqtt)