Zigbee2MQTT Home Assistant: Complete Setup Guide

If you want the most flexible and device-compatible Zigbee experience in Home Assistant, Zigbee2MQTT is the answer. Where Home Assistant's built-in Zigbee integration (ZHA) works for many setups, Zigbee2MQTT goes further — bridging your Zigbee network to an MQTT broker and exposing every device directly to Home Assistant with granular control. As of June 2026, version 2.12.0 supports over 5,400 devices from 577 vendors, making it the most comprehensive Zigbee bridge available. This guide walks you through everything from first install to your first paired device.

What Is Zigbee2MQTT?

Zigbee2MQTT is an open-source bridge that connects a Zigbee USB coordinator to an MQTT broker. Every Zigbee device in range publishes its state to MQTT topics — temperature, on/off status, battery level — and Home Assistant subscribes to those topics via the MQTT integration. The result is fully local, cloud-free control with no third-party accounts, no monthly fees, and no dependency on a manufacturer's servers.

The project is maintained by Koen Kanters and a large open-source community. Devices are supported through a shared device database, which means new products are frequently added — often within days of release.

Zigbee2MQTT vs ZHA: Which Should You Use?

Home Assistant ships with Zigbee Home Automation (ZHA), a native integration that requires no extra software. For simple setups with a handful of devices from mainstream brands, ZHA is perfectly capable. However, Zigbee2MQTT has several compelling advantages:

• Device support: Z2M supports over 5,400 devices; ZHA's list is shorter and some niche devices — particularly from Chinese brands like Tuya and SONOFF — are only fully supported in Z2M.
• Granular control: Z2M exposes device-specific features (e.g. a bulb's colour loop speed or a sensor's reporting interval) that ZHA often hides.
• MQTT ecosystem: Because Z2M publishes to MQTT, any system that understands MQTT — Node-RED, your own scripts, other hubs — can consume the data without touching Home Assistant at all.
• Debugging: Z2M includes a built-in web frontend that shows raw device messages, network topology, and OTA update status — invaluable for troubleshooting.
• Reliability: A separate process means Z2M can survive a Home Assistant restart without losing your Zigbee network state.

If you already have a working Home Assistant installation and plan to grow your Zigbee network beyond a dozen devices, Z2M is the better long-term choice.

What You Need Before You Start

• Home Assistant OS or Supervised install — the add-on store is only available on these installation types (not Docker or Core).
• A Zigbee USB coordinator — the SONOFF Zigbee 3.0 USB Dongle Plus is a popular, well-supported choice in the UK at around £15–£20. It is based on the CC2652P chipset and works with Z2M out of the box.
• An MQTT broker — the Mosquitto broker add-on, available free in the Home Assistant add-on store, is the standard choice.
• One or more Zigbee devices to pair.

For guidance on choosing the right USB stick, see our UK Zigbee coordinator guide, which covers chipset differences, range, and UK availability in detail.

Step 1 — Install Mosquitto Broker

Before installing Zigbee2MQTT, you need a running MQTT broker. In Home Assistant:

• Go to Settings → Add-ons → Add-on Store.
• Search for Mosquitto broker and install it.
• Start the add-on and enable Start on boot and Watchdog.
• Navigate to Settings → Devices & Services — Home Assistant should auto-discover the MQTT integration. Accept it.

Step 2 — Install the Zigbee2MQTT Add-on

The Zigbee2MQTT add-on is not in the default Home Assistant add-on store; you need to add the community repository first.

• In the Add-on Store, click the three-dot menu in the top-right corner and choose Repositories.
• Add the URL: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt and click Add.
• Refresh the page — the Zigbee2MQTT add-on will now appear. Install it.
• Do not start it yet — you need to configure the coordinator first.

Step 3 — Identify Your USB Coordinator Port

Plug your USB dongle into the Home Assistant host. To find the device path:

• Go to Settings → System → Hardware and click the three-dot menu, then All Hardware.
• Look for a USB serial device — typically /dev/ttyUSB0, /dev/ttyUSB1, or /dev/ttyACM0. For the SONOFF Dongle Plus, it often appears as /dev/ttyUSB0.
• Note the path — you will enter it in the Z2M configuration.

Step 4 — Configure Zigbee2MQTT

In the Zigbee2MQTT add-on page, click the Configuration tab. Set the following in the YAML editor:

• serial: port: /dev/ttyUSB0 — replace with your detected path.
• mqtt: server: mqtt://core-mosquitto — this is the internal address of the Mosquitto add-on.
• Leave homeassistant: true enabled — this activates MQTT discovery so devices appear automatically in HA.

Save the configuration, then Start the add-on. Check the Log tab — you should see Zigbee2MQTT started successfully within a few seconds. If you see port errors, double-check the serial path.

Step 5 — Pair Your First Zigbee Device

With Z2M running, open the Zigbee2MQTT frontend via Open Web UI in the add-on page. To pair a device:

• Click the Permit join toggle at the top of the frontend — this opens the network to new devices for 255 seconds by default.
• Put your Zigbee device into pairing mode (usually holding a button for 5–10 seconds; refer to your device manual).
• The device will appear in the Devices list, usually within 30 seconds.
• Once paired, disable Permit join again to keep your network secure.
• In Home Assistant, go to Settings → Devices & Services → MQTT — the new device will appear automatically through MQTT discovery.

Key Benefits at a Glance

• Local control: All communication stays on your local network — no cloud dependency, no internet required for devices to work.
• Massive device library: Over 5,400 supported devices including budget brands rarely supported elsewhere.
• MQTT flexibility: Plug any MQTT-capable system into the same broker — Node-RED, custom scripts, InfluxDB, and more.
• OTA updates: Push firmware updates to supported Zigbee devices directly from the Z2M frontend.
• Network map: Visualise your Zigbee mesh topology — see which devices are acting as routers to extend your range.
• Groups: Create Zigbee-level groups so multiple bulbs react simultaneously with no automation lag.

Troubleshooting Tips

Coordinator not found: Try unplugging and replugging the dongle, then check the hardware page again. Using a USB extension cable to move the dongle away from the host can also reduce interference from USB 3.0 ports.

Device won't pair: Check whether the device is in the supported list on zigbee2mqtt.io and follow the device-specific pairing instructions listed there. Some devices require multiple reset attempts.

MQTT connection refused: Confirm the Mosquitto add-on is running and that you used mqtt://core-mosquitto (not localhost) as the server address inside the Z2M configuration.

For further reading: see our Matter vs Zigbee vs Z-Wave protocol comparison and our guide to Home Assistant MQTT setup.