How to Set Up Zigbee2MQTT (or ZHA) in Home Assistant
How to set up Zigbee2MQTT in Home Assistant, plus the ZHA path. Choose a coordinator, pair devices, and avoid the USB3 and channel mistakes that break networks.
By HomeOS Lab · Last updated 4 September 2026
There are two well supported ways to run a Zigbee network inside Home Assistant, and both of them work. ZHA is the integration built into Home Assistant. Zigbee2MQTT (often shortened to Z2M) is a separate project that talks to Home Assistant over an MQTT broker. This guide walks through choosing between them and then setting up either one with a USB or Ethernet coordinator such as the SONOFF ZBDongle-E, the Home Assistant Connect ZBT-1, or the SMLIGHT SLZB-06. It is an opinionated guide: rather than sit on the fence, it says plainly where each option earns its keep.
ZHA or Zigbee2MQTT, and how I decide
ZHA is the path of least resistance. It ships with Home Assistant, it discovers most coordinators automatically, and there is no extra service to babysit. If you are new to Zigbee and you want lights and sensors working tonight, ZHA is a reasonable default and I would not talk you out of it.
Zigbee2MQTT trades a little setup effort for two things I care about: broader device support and finer control. When a device is brand new or slightly obscure, Z2M often supports it first, and its device pages document exactly which settings each product exposes. You also get a clean web frontend with a map of your mesh, per device OTA firmware updates, and the ability to rename and configure things without digging through YAML.
The cost is that Zigbee2MQTT needs an MQTT broker running, which is one more moving part. If that broker goes down, your Zigbee devices stop reporting to Home Assistant until it comes back. ZHA has no such dependency because it lives inside Home Assistant itself.
My honest opinion, and you are free to disagree: most people who plan to grow past a handful of devices will end up happier on Zigbee2MQTT, and the extra half hour of setup pays for itself the first time you hit a device ZHA does not fully support. If you never expect to go beyond a starter kit, that math flips and ZHA wins on simplicity.
One thing that is true for both: the coordinator does the heavy lifting, not the software. A good coordinator on a USB extension cable will behave well under ZHA and under Z2M alike.
Preparing the coordinator before you touch software
Whichever path you pick, the physical setup is the same, and getting it right up front saves hours of "why is this device dropping off" later.
Plug the coordinator into a USB extension cable rather than directly into the machine. This is not optional advice in my book. USB 3.0 ports and the SSDs next to them throw off interference right in the 2.4 GHz band that Zigbee uses, and a coordinator sitting flush against the case will pick up that noise. A cheap USB 2.0 extension of 0.5 to 1 metre moves the antenna clear of the mess. The SMLIGHT SLZB-06 sidesteps this entirely because it connects over Ethernet and can sit anywhere in the house.
If your coordinator is an Ethernet or PoE unit, give it a fixed address. Assign a DHCP reservation on your router so the coordinator keeps the same IP, because both ZHA and Z2M address a network coordinator by its IP and port.
Firmware is worth a quick check but not an obsession. Coordinators generally ship with working firmware, and you do not need the newest build to get started. I would only flash firmware if you hit a specific bug that a newer version is documented to fix.
Have one Zigbee device ready to pair, ideally a mains powered one like a smart plug. Mains powered devices act as routers and extend the mesh, and pairing one first gives you a stronger network to add battery sensors to afterward.
The ZHA path
ZHA setup is short. In Home Assistant go to Settings, then Devices & Services, then Add Integration, and search for Zigbee Home Automation.
Home Assistant will usually detect a plugged in coordinator and suggest the serial port for you. For a USB stick that looks like /dev/serial/by-id/..., and I recommend picking the by-id entry rather than /dev/ttyUSB0, because the by-id name stays stable across reboots even if the port number shifts. For a network coordinator like the SLZB-06, choose the manual option and enter its address as a socket, for example socket://192.168.1.50:6638.
ZHA reads the radio type from the coordinator, so you rarely choose it by hand. Confirm the settings, let it form the network, and you are done with the integration itself.
To pair a device, open the ZHA integration, click Add Device, and put your Zigbee device into pairing mode. That step varies by product, but it is often a long press on a button or a specific number of quick presses; the device manual will say. New devices appear with their model detected and land in your Home Assistant device list straight away.
If a device pairs but shows up with the wrong name or missing controls, note that and move on. ZHA's coverage is good, and edge cases here are one of the reasons some people prefer Z2M.
The Zigbee2MQTT path
This route has more steps because Z2M is its own service. I will go in the order that avoids backtracking.
First, install an MQTT broker. On Home Assistant OS the easiest is the Mosquitto broker add-on. Go to Settings, then Add-ons, open the add-on store, install Mosquitto broker, and start it. Home Assistant will normally discover the MQTT integration on its own once Mosquitto is running; accept it when prompted. If you prefer explicit credentials, create a dedicated Home Assistant user for MQTT and note the username and password, because Z2M will need them.
Second, install the Zigbee2MQTT add-on. Add the official Z2M add-on repository if it is not already listed, then install and open the add-on. Do not start it yet, because it needs to know about your coordinator first.
Third, tell Z2M about the coordinator. Open the add-on Configuration tab and set the serial adapter. For the SONOFF ZBDongle-E and the Connect ZBT-1, which use a Silicon Labs radio, the adapter is ember and the port is the by-id serial path. For a TI based coordinator such as the SONOFF ZBDongle-P, the adapter is zstack. For the SLZB-06 over the network, set the port to a tcp://192.168.1.50:6638 style address that matches your unit's coordinator port. A minimal serial block looks like this:
serial:
port: /dev/serial/by-id/usb-Silicon_Labs_...-if00-port0
adapter: ember
Fourth, point Z2M at the broker. In the same configuration, set the MQTT server to mqtt://core-mosquitto:1883 when you use the Mosquitto add-on, and add the username and password if you created dedicated credentials.
Fifth, enable the frontend so you get the web UI. In the add-on configuration set:
frontend:
port: 8099
Now start the add-on, watch the log tab until it reports the coordinator started and the network formed, and open the Z2M web interface. To add devices, click Permit join, put your device into pairing mode, and watch it appear in the Z2M device table with its model and exposed features. From there Home Assistant picks up each device automatically through MQTT discovery.
If the add-on log shows an error opening the port, the usual causes are a wrong by-id path or the coordinator still being claimed by another integration. Stop ZHA before running Z2M against the same coordinator, since only one piece of software can own a coordinator at a time.
Gotchas that cost people an afternoon
A few problems come up often enough that they are worth calling out before they find you.
The USB3 interference issue is the single most common cause of a flaky Zigbee network, and I mentioned the extension cable earlier for exactly this reason. If devices at the edge of your house keep dropping, the cable is the first thing to try, not more repeaters.
Channel choice matters more than people expect. Zigbee and 2.4 GHz WiFi share the same spectrum, so a Zigbee network sitting on top of a busy WiFi channel will suffer. ZHA defaults to channel 15 and Z2M defaults to channel 11. If your WiFi runs on channels 1, 6, or 11, pick a Zigbee channel that dodges them, with 15, 20, or 25 being the usual candidates. Set the channel before you pair a pile of devices, because changing it afterward means re-pairing everything.
Backups and migration deserve a word. Both ZHA and Z2M can export a coordinator backup that holds the network key, PAN ID, and channel. In principle you can carry that network across from ZHA to Z2M, or the reverse, so your devices stay joined without re-pairing. In practice I treat a clean re-pair as the reliable fallback when a migration acts up, and I keep a current backup before making any change to the coordinator or the software. Do not skip the backup step; it is the difference between a five minute recovery and rebuilding your whole network by hand.
One more, since it surprises people: you cannot run ZHA and Zigbee2MQTT against the same coordinator at the same time. If you want to try both, either use two coordinators or fully disable one before enabling the other.
FAQ
Do I need Zigbee2MQTT if I already use ZHA?
No. If ZHA supports all your devices and you are happy with it, there is no reason to switch. Move to Z2M when you hit a device ZHA handles poorly, or when you want features like the mesh map and per device OTA updates.
Can I use the same coordinator for both ZHA and Zigbee2MQTT?
Not simultaneously. A coordinator can only be controlled by one piece of software. You can switch which one owns it, but you must disable the other first, and you should back up the network before you do.
Which is better for a large network?
Both scale to well over a hundred devices when the mesh has enough mains powered routers. I lean toward Zigbee2MQTT for large or unusual device mixes because of its wider device support, but a healthy ZHA network with good routers holds up fine.
Does Zigbee2MQTT need the internet to work?
No. Z2M and the MQTT broker run locally on your Home Assistant machine, and your Zigbee network keeps working offline. Internet is only involved when you fetch OTA firmware updates.
Why do my battery sensors keep going unavailable?
Usually weak mesh coverage or coordinator interference. Add a mains powered router device between the coordinator and the sensor, and confirm your coordinator is on a USB extension cable away from USB3 ports and SSDs.
Where to go next
To choose the hardware this whole guide depends on, start with our roundup of the best Zigbee coordinators for Home Assistant.
If your network is already up but misbehaving, read how to fix a flaky Zigbee network in Home Assistant for the interference and mesh fixes in more depth. Still deciding on a wireless standard at all? Compare the options in Zigbee vs Z-Wave vs Thread vs Wi-Fi. And if you are planning the machine underneath everything, our guide to building a reliable Home Assistant hub covers where the coordinator fits.
For a closer look at two coordinators mentioned above, see our reviews of the SONOFF ZBDongle-E Zigbee coordinator and the Home Assistant Connect ZBT-1.