Zigbee2MQTT is the most flexible way to use Zigbee devices with Home Assistant. It supports more device models than the built-in ZHA integration, exposes more device features, and benefits from active community development. The trade-off is that it takes a bit more setup work upfront.
This guide walks through the complete Zigbee2MQTT setup for Home Assistant in 2026: choosing a coordinator, installing the software, pairing your first device, and avoiding the gotchas that send people back to ZHA in frustration.
Why Zigbee2MQTT vs ZHA
Home Assistant offers two ways to talk to Zigbee devices:
- ZHA (Zigbee Home Automation): a built-in integration. No additional software to install beyond Home Assistant itself. Smaller device support list, simpler setup.
- Zigbee2MQTT (Z2M): a separate program (typically run as a Home Assistant add-on) that bridges Zigbee to MQTT, which Home Assistant subscribes to. Larger device support list, more features per device, more setup work.
For someone with one or two common-brand Zigbee devices (Hue, IKEA, Aqara), ZHA is the faster path to working automation. For someone planning to grow a Zigbee network with mixed-brand devices, niche models, or any device made by a manufacturer outside the top 10, Zigbee2MQTT is the safer long-term bet. Z2M's supported device list is approximately 3,000 devices; ZHA's is meaningfully smaller, though it has been catching up.
You can switch from one to the other later, but the migration requires re-pairing every device. Pick once and stick with it for at least your first year.
Step 1: Pick a Zigbee coordinator
A Zigbee coordinator is a small USB device with a Zigbee radio that lets your Home Assistant server talk to Zigbee devices. The coordinator is the most consequential hardware choice in this entire process. The wrong coordinator works for a few months and then frustrates you with range issues, dropouts, or the inability to pair a particular device.
The two most-recommended coordinators in 2026:
Home Assistant Connect ZBT-1 (formerly SkyConnect)
Nabu Casa's official coordinator. Silicon Labs EFR32MG21 chipset. Supports Zigbee 3.0 with the option to flash it to OpenThread firmware for Thread/Matter support (one or the other, not both simultaneously). Solid build quality, well-documented, and the official choice if you want first-party support.
Price: typically $25 to $40 depending on region.
Sonoff ZBDongle-P
Texas Instruments CC2652P chipset. Widely deployed in the Zigbee2MQTT community, with strong device compatibility and the highest stable transmit power of any commonly available consumer coordinator (good for larger homes). Available globally and inexpensive.
Price: typically $20 to $30.
Note: the Sonoff ZBDongle-E (an EFR32MG21-based variant, like SkyConnect) exists but is generally not recommended for Zigbee2MQTT because of weaker community-tested firmware. Stick with the ZBDongle-P (P, not E).
USB extension cable (do not skip this)
The single most overlooked accessory: a 1-meter USB 2.0 extension cable to physically separate the coordinator from the Home Assistant server. USB 3.0 ports generate radio interference that bleeds into the 2.4 GHz band Zigbee uses. Plug the coordinator directly into the back of a Raspberry Pi or mini PC and you will see device dropouts and range problems that vanish when you add a 1m extension cable.
Any cheap USB 2.0 extension cable will do.
Step 2: Install Mosquitto MQTT broker
Before installing Zigbee2MQTT, install the Mosquitto broker add-on. This is the MQTT broker that Z2M will publish messages to and Home Assistant will subscribe to.
- Go to Settings → Add-ons → Add-on Store.
- Find "Mosquitto broker" in the Official add-ons section.
- Install. Start. Enable "Start on boot" and "Watchdog".
- Go to Settings → People → Users → Add user. Create a user called "mqtt" with a password (you will need this later). Disable "Administrator" for this user; it only needs to log in to MQTT.
That is it for Mosquitto. The defaults are fine for residential use.
Step 3: Install Zigbee2MQTT
The easiest path is the Zigbee2MQTT add-on, maintained by Kevin Hartig.
- Go to Settings → Add-ons → Add-on Store → three-dot menu → Repositories.
- Add this repository:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt - Refresh the add-on store. Find "Zigbee2mqtt" in the new repository section.
- Plug your Zigbee coordinator into the Home Assistant server (via the USB extension cable).
- Install Zigbee2mqtt. Do not start yet.
- In the add-on's Configuration tab, point the serial port at your coordinator. Common values:
/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...or/dev/serial/by-id/usb-Nabu_Casa_SkyConnect_.... Find the exact value via the Home Assistant Terminal add-on withls /dev/serial/by-id/. - Set the MQTT user and password to the ones you created in step 2.
- Start the add-on. Enable "Start on boot" and "Watchdog".
Open the add-on's Web UI. You should see the Zigbee2MQTT dashboard with a "Permit join" toggle. If you see that, the coordinator is talking to Z2M correctly.
Step 4: Pair your first device
Pairing is the same conceptual flow for every device, but the specific button presses vary:
- In the Zigbee2MQTT Web UI, click "Permit join (All)" at the top.
- Put your device into pairing mode. This is device-specific: hold a button for 5 seconds, press a reset pinhole, toggle power three times, etc. The Zigbee2MQTT device support page has per-device instructions.
- Watch the Zigbee2MQTT log for the device joining. You should see lines like
Successfully interviewedfollowed by the device's auto-generated name. - Rename the device in the Web UI to something meaningful (
front_door_sensor,kitchen_light_3, etc.). Use lowercase with underscores; this becomes the entity name in Home Assistant. - Click "Permit join" off when finished. Leaving it on creates a security hole and makes nearby Zigbee devices behave unpredictably.
Home Assistant should auto-discover the device within seconds. Check Settings → Devices and Services → MQTT to confirm.
Step 5: Build a Zigbee network map for sanity
The Zigbee2MQTT Web UI includes a Map view that shows your Zigbee network topology: which devices are routers, which are end devices, which connections are strong, which are weak. This map is the single best debugging tool when something is acting up.
Open it under Map. Wait 30 seconds for the routing to populate. Devices marked as routers (typically anything mains-powered: smart plugs, in-wall switches, smart bulbs) extend your Zigbee network. Devices marked as end devices (battery-powered sensors, buttons) rely on the routers to relay traffic.
A healthy Zigbee network has multiple routers spread around the house, with end devices showing strong (green) connections to nearby routers. If the map shows long red lines or devices connected only to the coordinator, you need more routers in those zones. Adding a $10 smart plug as a relay often fixes a flaky sensor.
Common gotchas
Channel conflicts with WiFi
Zigbee and 2.4 GHz WiFi share the same band. Zigbee channels 11-26 overlap with WiFi channels 1-13. If your WiFi is on channel 1 (which is Zigbee 11-13) or channel 6 (Zigbee 17-19) or channel 11 (Zigbee 23-25), the Zigbee network will suffer interference.
The defaults in Z2M are channel 15 (between WiFi 1 and 6) or channel 20 (between WiFi 6 and 11). Most installs work fine on default. If you have problems, move your WiFi to channel 1 or 11 (not the in-between channels) and put Zigbee on whichever distant channel works best.
Coordinator firmware updates
Coordinators ship with whatever firmware was current at manufacture, which may not be current. After initial setup, check whether your coordinator firmware is up to date. The Z2M Web UI shows the firmware version; the project page documents how to update for each coordinator model.
USB 3.0 interference
Mentioned earlier but worth repeating: use a USB extension cable. USB 3.0 ports emit electromagnetic noise in the 2.4 GHz range. Plugging a Zigbee coordinator directly into a USB 3.0 port (or even adjacent to one) reliably breaks pairing and causes random dropouts.
Migrating from ZHA to Z2M
If you started with ZHA and want to switch to Zigbee2MQTT, the migration requires re-pairing every device. There is no in-place conversion. Plan a Saturday morning for this if you have more than 10 devices.
What to install next
With Zigbee2MQTT working, the next step is curating your device collection. For a starter list of Zigbee devices that work well with Home Assistant, see our Best Zigbee Devices for Home Assistant guide. For a broader look at the integrations and add-ons worth installing alongside Z2M, see Best Home Assistant Integrations in 2026.
Frequently asked questions
Should I use Zigbee2MQTT or ZHA with Home Assistant?
Zigbee2MQTT supports a wider range of devices, has more mature community development, and exposes more device features. ZHA is built into Home Assistant and is simpler to set up. For most users with mixed-brand Zigbee devices, Zigbee2MQTT is the better long-term choice. For users with simple needs and only common-brand devices, ZHA is faster to get running.
What Zigbee coordinator should I buy?
The Home Assistant SkyConnect (now Connect ZBT-1) and the Sonoff ZBDongle-P are the two most-recommended USB coordinators in 2026. Both support Zigbee 3.0, work reliably with Zigbee2MQTT, and cost between $20 and $40. Pick SkyConnect if you also want Thread/Matter support; pick ZBDongle-P if you want maximum compatibility and the lowest price.
Why do I need an MQTT broker for Zigbee2MQTT?
Zigbee2MQTT does what its name says: it translates Zigbee device messages into MQTT messages and back. Home Assistant subscribes to those MQTT messages to know what each device is doing. The MQTT broker is the middleman that holds the messages. The Mosquitto add-on is the standard choice and installs in one click.
Do I really need a USB extension cable?
Yes. USB 3.0 ports emit RF interference in the 2.4 GHz band Zigbee uses. Plugging a Zigbee coordinator directly into a USB 3.0 port (or adjacent to one) causes pairing failures and random device dropouts. A 1-meter USB 2.0 extension cable is the universal fix and costs about $5.
How do I avoid WiFi interference with Zigbee?
Put your WiFi on channels 1 or 11 (not the in-between channels 4, 6, 8, 9). Put Zigbee on channel 15 (the default) or channel 20. This way the two technologies sit in different parts of the 2.4 GHz band and do not collide.
Curated with AI assistance via Charmed.