What is Zigbee2MQTT

Want total control over your Zigbee devices — all locally, without any cloud apps or vendor hubs?
With Zigbee2MQTT, your Home Assistant setup can manage over 3,000 Zigbee devices directly, offering deeper insight, faster performance, and complete privacy.

This guide shows you exactly how to install and configure Zigbee2MQTT, connect it to the Mosquitto MQTT broker, and pair your first Zigbee device — step by step.

What Is Zigbee2MQTT (and Why Use It)

Zigbee2MQTT is an open-source service that connects your Zigbee coordinator (USB or LAN adapter) to Home Assistant through MQTT — a lightweight local communication protocol. It replaces proprietary hubs (like Aqara or Philips Hue bridges) and gives you full control of your Zigbee network inside Home Assistant.

Why People Choose It

• Universal compatibility: Works with thousands of Zigbee devices from brands like Sonoff, Aqara, Tuya, and Philips.

• Completely local: No cloud connections, no vendor apps.

• Powerful diagnostics: View device signal strength, routing maps, and battery levels in real time.

• Easy backups: Move your entire Zigbee network to new hardware in minutes.

What You’ll Need

• A running Home Assistant OS installation

• A Zigbee coordinator (e.g. Sonoff Zigbee 3.0 USB Dongle Plus, SMLight SLZB-06, etc)

Step 1 — Add the Zigbee2MQTT Repository

Zigbee2MQTT isn’t built into Home Assistant by default, so you’ll need to add it manually.

1. Go to Settings → Add-ons → Add-on Store

2. Click the ⋮ (three dots) in the top-right corner → select Repositories

3. Paste this link:
   https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

4. Click Add, then Close

After a few seconds, Zigbee2MQTT will appear in your Add-on Store list.

Step 2 — Install Zigbee2MQTT

1. In the Add-on Store, find Zigbee2MQTT. Make sure it is Zigbee2MQTT not "Zigbee2MQTT Proxy" or "Zigbee2MQTT Edge".

2. Click Install (this may take a few minutes). Once done it should be in your add-ons.
   

Step 3 — Configure the Zigbee Coordinator

Zigbee2MQTT needs to know which coordinator you’re using and how to connect to it.

1. Go to Settings → System → Hardware → All Hardware
   

2. Find your coordinator and copy its serial path. It usually looks like:
   /dev/serial/by-id/usb-... or for Ethernet coordinators tcp://192.168.1.XX:6638

3. Go back to Zigbee2MQTT → Configuration → serial and set:

   
   

   under serial

   port: [your serial or tcp path]

   adapter: [adapter type]

   

4. Replace [adapter type] with one of the following based on your coordinator:

   • ember → For Silicon Labs–based coordinators (e.g. Sonoff 3.0, SMLight SLZB-06, TubeZB-E)

   • ezsp → For older Silicon Labs dongles (firmware before 7.4.x)

   • zstack → For Texas Instruments–based coordinators (e.g. CC2652, CC1352)

   • deconz → For ConBee or RaspBee adapters

Tip: Always use the full /dev/serial/by-id/... path instead of /dev/ttyUSB0, as it stays consistent after reboots.

Click Save once done.

Step 4 — Install and Configure Mosquitto (MQTT Broker)

Zigbee2MQTT communicates with Home Assistant through MQTT.

1. Go to Settings → Add-ons → Add-on Store

2. Search for Mosquitto broker → click Install

3. After installation, click Start

4. Go to Settings → People → Users → Add user

   • Create a new user (e.g. mqtt)

   • Assign a strong password

   • Do not give admin access

5. Return to Zigbee2MQTT → Configuration → mqtt

6. Set:

   under mqtt

   server: mqtt://core-mosquitto:1883

   base_topic: zigbee2mqtt

   user: mqtt 

   password: YOUR_PASSWORD 

   

7. Click Save, then restart both Mosquitto and Zigbee2MQTT

 Step 5 — Start Zigbee2MQTT

1. Go to Zigbee2MQTT → Info

2. Enable:

   • ✅ Start on boot

   • ✅ Watchdog

   • ✅ Show in sidebar

3. Click Start 

Your Zigbee network is now live! If you have any questions that aren't answered in our FAQs then feel free to send a message or leave a comment. 

Optional — Pair Your First Zigbee Device

Here’s how to pair a Sonoff SNZB-04 Door/Window Sensor (or any other Zigbee device):

1. In Zigbee2MQTT, click Open Web UI

2. Click Permit join (All) — the message “Joining is enabled” will appear

3. On your Zigbee device (device dependant) put it into pairing mode. 

4. Wait a few seconds — the new device will appear in Zigbee2MQTT as:
   SONOFF SNZB-04 (0x00124b00294a1234) or whatever your device is called.

5. Click it → rename it (e.g. “Front Door Sensor”)

6. Test it by opening and closing the door or triggering the sensor/device — you’ll see the state change in both Zigbee2MQTT and Home Assistant

Once added, click Permit join (All) again to disable pairing mode for security.

FAQ

Can I use Zigbee2MQTT and ZHA at the same time?

Yes — but each integration must have its own Zigbee coordinator. A single USB dongle can only manage one Zigbee network at a time.

Do I need MQTT installed?

Yes. Zigbee2MQTT communicates through an MQTT broker. The easiest option is to install the Mosquitto broker add-on from the Home Assistant Add-on Store. Once installed and started, Zigbee2MQTT connects automatically using the internal Home Assistant address:
mqtt://core-mosquitto:1883
You’ll just need to create a non-admin user (for example, “mqtt”) in Home Assistant and enter that username and password in Zigbee2MQTT’s configuration.

How do I back up my Zigbee network?

In the Zigbee2MQTT dashboard, go to Settings → Advanced → Backup and click Download Backup. This file contains your Zigbee network key and paired device list. You can restore it later if you migrate to a new coordinator or reinstall Home Assistant.

Does this work offline once installed?

Yes. After setup, Zigbee2MQTT runs entirely on your local network with no cloud services required.