Home Assistant Zigbee2MQTT Setup: A Clean Start-to-Finish Guide
Zigbee2MQTT setup goes wrong in a predictable order: the broker is not reachable, the coordinator path moves after a reboot, or pairing is opened before the adapter is actually talking. This guide puts the four moving parts in the order they have to work, checks each one, and shows where a failure actually happened.
The short answer
Zigbee2MQTT is four moving parts, and the order is fixed. First an MQTT broker, running and reachable. Then the Zigbee coordinator, on a stable serial path and away from USB 3.0 ports and the server's Wi-Fi radio. Then Zigbee2MQTT itself, pointed at both. Last, Home Assistant's MQTT integration, so Zigbee2MQTT's discovery messages become entities. Pair devices only after the first four are confirmed working.
An MQTT broker you control, reachable from both the Home Assistant host and the Zigbee2MQTT host.
A supported Zigbee coordinator on the stable /dev/serial/by-id/ path, on a USB 2.0 extension cable.
Pointed at the broker and at the coordinator. It creates the network and its network key on first start.
Added in Home Assistant against the same broker, with discovery on. This is what creates your entities.
We run 46 Zigbee devices on a Sonoff ZBDongle-E in our own home — so the checks below come from a live network, not spec sheets.
Before you start: a five-point pre-flight
Run this check first. Each item maps to a stage in the steps below, and a failure here is much cheaper to fix now than after you have paired forty devices.
- 1Coordinator is on coordinator firmware
A coordinator that is running router firmware will not start a network. Confirm the firmware role against the manufacturer's official instructions before you begin, and stop there if you are unsure.
- 2Coordinator is on a USB 2.0 extension cable
1–2 m of USB 2.0 extension, away from USB 3.0 ports and away from the server's Wi-Fi radio. On our bench this beat every hardware upgrade we tried.
- 3Broker is reachable
Confirm the broker answers from the Zigbee2MQTT host before you install Zigbee2MQTT. A broker that only listens on localhost is the single most common reason the first start fails.
- 4You know which install path you are on
Add-on or container. The chooser below settles it in one line.
- 5You have a backup plan for the network key
Zigbee2MQTT generates a network key when it creates the network. Copy the Zigbee2MQTT data directory somewhere safe before you pair the first device. Losing it means re-pairing everything.
Stop and check the manual
In-wall modules, relays, dimmers, switches, and anything wired into household mains must be installed by a qualified electrician with the circuit de-energized, following the manufacturer's manual. If you are not qualified to do that work, stop here and call an electrician. For any step a manufacturer documents as irreversible — including coordinator firmware flashing — the official manual overrides this page.
Which install path fits your Home Assistant?
| Your setup | Install Zigbee2MQTT as | Why |
|---|---|---|
| Home Assistant OS or Supervised | The Zigbee2MQTT add-on | The add-on store is available, so the broker and Zigbee2MQTT live in the same managed place |
| Home Assistant Container or Core | Its own container next to your broker | There is no add-on store on these install types |
| You already run ZHA on the same coordinator | Stop ZHA first, or use a second coordinator | One coordinator runs one Zigbee stack at a time |
| You already run a Sonoff ZBDongle-P on Z-Stack | Stay on the P | It is a proven path — do not migrate for fun |
| Your server sits in a metal rack or a closet | Consider an Ethernet/PoE coordinator you can place remotely, such as the SMLIGHT SLZB-06 | The radio needs to be away from the metal and the noise, not the software |
The setup, in order
Do not skip ahead. Step 6 is the gate — if Zigbee2MQTT is not talking to the coordinator, nothing after it will work.
Stand up the MQTT broker
Install and start your broker — Mosquitto is the usual choice on Home Assistant — and decide the username and password Zigbee2MQTT will use. Confirm it is reachable from the Zigbee2MQTT host before you continue. If your broker only listens on localhost, fix that now.
Place the coordinator
Plug the coordinator into a USB 2.0 port using a 1–2 m USB 2.0 extension cable. Keep it clear of USB 3.0 ports and away from the server's Wi-Fi radio. This is placement, not shopping: on our own network it did more than any chipset change.
Find the stable serial path
Read the coordinator's device path and use the
/dev/serial/by-id/...form. A numbered/dev/ttyUSB*path can move after a reboot and will silently break Zigbee2MQTT later.Install Zigbee2MQTT
Add-on or container, matching the path you chose above. Give it a persistent data directory — that directory holds the network key and the coordinator backup.
Configure Zigbee2MQTT
Set the MQTT section (broker address, username, password) and the serial section (the by-id port, plus the adapter family — zstack for CC2652P-class coordinators such as the Sonoff ZBDongle-P, ember for EFR32MG21/EFR32MG24-class coordinators such as the Sonoff ZBDongle-E). Leave the generated network key alone and keep your copy of the data directory.
Start it and read the log
This is the gate. Zigbee2MQTT should report the coordinator it found and the network it created or joined. If it cannot open the serial port, stop and fix that — check the path, the cable, and whether another process is holding the coordinator. Do not continue to pairing until this step is clean.
Add the MQTT integration in Home Assistant
Add the MQTT integration against the same broker and make sure discovery is on. Zigbee2MQTT's discovery messages are what create your entities, so nothing appears in Home Assistant until this step is done.
Pair devices, one at a time
Open permit join in Zigbee2MQTT, put a single device into pairing mode, and wait for it to be interviewed before starting the next one. Battery-powered devices are sleepy — keep them awake through the interview. Close permit join when you are finished.
What a finished setup looks like
- ✓Zigbee2MQTT starts without serial errors and reports its coordinator.
- ✓The Zigbee2MQTT interface lists the devices you paired, with a model and a link quality.
- ✓Home Assistant shows the new entities under the MQTT integration.
- ✓A device you physically trigger changes state in Home Assistant within a moment.
- ✓Permit join is off, and the Zigbee2MQTT data directory — network key and coordinator backup — is copied somewhere outside the host.
If any of these is false, go back to the step that covers it rather than re-pairing devices.
Six mistakes that cost a weekend
An open pairing window is an open door. Close it as soon as the device you were adding has been interviewed.
The number is assigned by the order the kernel sees devices. Add a second USB device and your coordinator becomes ttyUSB1. Always use the by-id path.
One coordinator runs one Zigbee stack at a time. Stop ZHA before starting Zigbee2MQTT, or give each stack its own coordinator.
The network key lives in the Zigbee2MQTT data directory. Without it, a rebuilt instance cannot rejoin your existing devices, and you are re-pairing the house by hand.
When devices drop, the first two things to check are placement and channel, not the coordinator's part number. Moving the dongle 1–2 m on a USB 2.0 extension fixed more on our bench than any upgrade we bought.
If the broker only binds to localhost, a Zigbee2MQTT instance on another host or in another container will never connect. Fix reachability before you debug anything else.
Edge cases and what to do
| Situation | What to do |
|---|---|
| New coordinator, keep devices | Restore the coordinator backup from the Zigbee2MQTT data directory into the new coordinator. We moved our whole 46-device network with zero re-pairing — and the mistake we hit was in the backup files, not the radio. Verify the backup before you start, not after. |
| ZHA is already installed | Stop ZHA before starting Zigbee2MQTT on the same coordinator. If you want both stacks live at once, use two coordinators. |
| Interview fails (Battery) | Sleepy end devices need to be awake. Keep the device awake through the interview and retry; if it still fails, follow the device manufacturer's own pairing and reset procedure. |
| Drops after reboot | Check the serial path first, then the USB extension. A path that changed from ttyUSB0 to ttyUSB1 looks exactly like a broken network. |
| Server in a rack/closet | Move the radio, not the software. An Ethernet/PoE coordinator such as the SMLIGHT SLZB-06 lets the radio sit in the open while the host stays where it is. |
| Wi-Fi/Zigbee interference | Zigbee and 2.4 GHz Wi-Fi share spectrum. Check that your Zigbee channel and your Wi-Fi channels are not fighting before you change any hardware. |
| Mains-powered device | Stop. In-wall modules and anything wired into household mains must be installed by a qualified electrician, with the circuit de-energized, following the manufacturer's manual. |
| Failure not listed | Stop guessing and go to the official Zigbee2MQTT documentation and the official Home Assistant documentation for the version you are running. If a device manual describes a different procedure, the manual wins. |
Frequently asked questions
Do I need Mosquitto if I already run an MQTT broker?
No. Mosquitto is a common choice, not a requirement. Zigbee2MQTT needs an MQTT broker it can reach — if you already run one, point Zigbee2MQTT at it and skip the broker install.
Can I run Zigbee2MQTT and ZHA at the same time?
Not on the same coordinator. One coordinator runs one Zigbee stack at a time. Run them side by side only with a separate coordinator for each.
Will switching to Zigbee2MQTT make me re-pair every device?
That depends on whether you still have the network key and the coordinator backup. If you are migrating between coordinators with the backup intact, you can keep the network — we moved 46 devices with zero re-pairing. Without the backup, you start the network over.
Which coordinator should I buy for Zigbee2MQTT?
Buy for placement and for the adapter family, not for a headline number. Our tested shortlist and the reasoning behind it are in Best Zigbee Coordinator for Home Assistant (2026) →
What is the difference between the zstack and ember adapters?
They are the two coordinator families Zigbee2MQTT talks to. zstack covers CC2652P-class coordinators such as the Sonoff ZBDongle-P; ember covers EFR32MG21/EFR32MG24-class coordinators such as the Sonoff ZBDongle-E. Set the one that matches the coordinator you actually plugged in.
How long does setup take?
We are not going to put a number on it. The variable is not the software — it is how many devices you are pairing and how many of them are sleepy battery devices that need waking.
Where to go next
Two pages pick up where this guide stops.