ZHA (Zigbee Home Automation integration)
ZHA is Home Assistant’s built-in Zigbee integration: plug a supported coordinator dongle into the machine running Home Assistant and it runs a Zigbee network natively — no separate software, no MQTT broker, no vendor hub. It is the simpler of the two big DIY Zigbee routes, with Zigbee2MQTT being the more configurable one.
ZHA is built on the zigpy library and ships inside Home Assistant, so devices appear directly as Home Assistant entities with no bridge layer. Standard-conforming Zigbee 3.0 devices generally just work; manufacturer quirks are handled by a community “quirks” library that plays the same role as Zigbee2MQTT’s converters, and coverage between the two projects overlaps heavily.
Choosing between ZHA and Zigbee2MQTT is a recurring Home Assistant question with a boring answer: ZHA for simplicity and tight HA integration, Zigbee2MQTT for maximum device-feature coverage, standalone operation, and finer control (per-device settings, a binding UI, a network map). Both use the same coordinator hardware, and migrating between them is possible with a coordinator backup, though device re-interviewing is usually involved.
| Installation | None — ZHA ships with Home Assistant and is added through a config flow |
|---|---|
| Zigbee stack | zigpy, with a radio library per chipset (Texas Instruments, Silicon Labs, ConBee, XBee) |
| Device quirks | zha-device-handlers, the equivalent of Zigbee2MQTT’s converters |
| Extra services needed | No MQTT broker and no second container |
| Supported hardware | The same dongles as Zigbee2MQTT — SONOFF ZBDongle-P and -E, SMLIGHT SLZB-06, Home Assistant Connect ZBT-1 |
| Backup | Network key, PAN ID, and channel exportable through zigpy for restore onto a new radio |
What you get without installing anything
ZHA is built on zigpy, a Python Zigbee implementation with a separate driver library per radio family. Plug in a supported dongle and Home Assistant offers to configure it; a few clicks later you have a working Zigbee network, and paired devices arrive as ordinary Home Assistant entities with no bridge, no broker, and no topic names to learn.
The integration covers more than beginners expect. Groups, per-cluster bindings, attribute reporting configuration, OTA firmware updates, network topology visualisation, and a raw cluster inspector are all reachable from the device pages or through services — the surface is less discoverable than Zigbee2MQTT’s frontend, but the capability is largely there.
The one thing you give up structurally is process isolation. The Zigbee stack lives inside Home Assistant, so a Home Assistant restart is a Zigbee restart, and a Home Assistant migration is a Zigbee migration. In a stable installation this is a non-event; if you tinker with your Home Assistant instance weekly, it is an argument for Zigbee2MQTT.
Quirks, and what happens without one
A quirk is a Python class that tells ZHA what a specific model really does — remapping clusters, correcting endpoint layouts, translating manufacturer-specific attributes into sensible entities. The zha-device-handlers repository plays exactly the role zigbee-herdsman-converters plays for Zigbee2MQTT, and the two projects share a lot of hard-won knowledge about the same hardware.
The interesting difference is the failure mode. Zigbee2MQTT tends to be explicit: an unknown device is unsupported until somebody writes a converter. ZHA falls back to generic cluster handling, so an unquirked device usually pairs and gives you something — often the standard functions, sometimes oddly named entities, occasionally an attribute exposed with no unit. That is friendlier for common hardware and more confusing for odd hardware, where you get a device that half works and no clear signal that it should do more.
Because both databases cover broadly the same devices, our compatibility signal treats them together: a device supported by Zigbee2MQTT is very likely to work under ZHA, and the 5,405 Zigbee devices we track are a reasonable proxy for either platform.
Radios, and one experiment worth knowing about
ZHA drives the same coordinators everyone else uses, and the same placement advice applies: get the dongle away from the machine on a USB extension cable, or use an Ethernet-attached radio like the SMLIGHT SLZB-06 and put it somewhere central. Coordinator choice matters far less than coordinator position.
One piece of history saves people a bad afternoon. Home Assistant shipped an option to run Zigbee and Thread simultaneously on a single Silicon Labs radio — the multiprotocol firmware on the Connect ZBT-1 and Yellow. It worked, but with enough reliability cost on both protocols that the guidance moved back to one radio per protocol. If you want Zigbee and Thread, budget for two radios rather than one clever one.
Migration in either direction is a backup-and-restore exercise, not a re-pairing marathon. Export the network from one platform, restore it on the other, and devices rejoin as they wake. Budget for a slow day of re-interviewing and for rewriting every automation that referenced entity names, because the two platforms name things differently.
Frequently asked questions
Should I use ZHA or Zigbee2MQTT?
ZHA if you want the simplest path: it is already in Home Assistant, needs no broker, and handles mainstream devices well. Zigbee2MQTT if you buy cheap or unusual hardware, want a binding UI and a network map, or want the Zigbee network to survive Home Assistant restarts independently. Both use the same dongles, so the decision is reversible with a network backup.
Which coordinators work with ZHA?
Anything zigpy has a driver for, which covers the mainstream: SONOFF ZBDongle-P (Texas Instruments) and ZBDongle-E (Silicon Labs), the Home Assistant Connect ZBT-1, SMLIGHT’s Ethernet and PoE coordinators, and older ConBee and XBee hardware. That is essentially the same list Zigbee2MQTT supports.
Can I run ZHA and Zigbee2MQTT at the same time?
Yes, with one dongle each and two separate Zigbee networks on different channels. People do this while migrating, or to keep a stable lighting network apart from an experimental one. What you cannot do is point both at the same radio or the same network — there is exactly one coordinator per Zigbee network.
Does ZHA support Zigbee bindings and groups?
Yes to both. Groups are created from the ZHA panel, and per-cluster bindings can be configured from the device page or through services, which lets a remote drive a bulb directly without Home Assistant in the path. The UI is less obvious than Zigbee2MQTT’s Bind tab, but the underlying capability is the same.
What happens to my Zigbee devices when Home Assistant restarts?
The Zigbee network goes down for the duration, because ZHA runs inside Home Assistant. Devices stay joined and reconnect on their own, and existing bindings keep working device-to-device throughout, but any automation that depends on Home Assistant will not fire during the restart. Zigbee2MQTT avoids this by running as a separate service.