How to Add Zigbee2MQTT to Home Assistant

Working out how to add Zigbee2MQTT to Home Assistant is mostly a matter of doing four things in the right order: install an MQTT broker, add the Zigbee2MQTT app repository, get through the onboarding page with the correct adapter and channel, then let MQTT discovery populate Home Assistant. The official documentation spreads those pieces across a dozen pages. This guide puts them in sequence and flags the settings that cost you a full re-pair if you change them afterwards.

Decide first: Zigbee2MQTT or ZHA, not both on one stick

Zigbee2MQTT and the built-in ZHA integration are alternatives, and they cannot share a coordinator. The Zigbee2MQTT FAQ states that each instance “only supports connecting a single dedicated Zigbee Coordinator radio adapter or module with a single Zigbee network”, and that the coordinator “cannot already be connected or used by any other application”. If you already run ZHA, adding Zigbee2MQTT means a second adapter or re-pairing every device. There is no supported in-place conversion.

The case for Zigbee2MQTT is its device library and a frontend that puts the network map, per-device settings and OTA updates in one place. Not committed to a radio yet? Start with Zigbee vs Z-Wave vs Thread.

What you need before you start

A supported adapter. The supported adapters page recommends three families: zStack (Texas Instruments) with the SONOFF ZBDongle-P, Electrolama zzh and TubesZB; EmberZNet (Silicon Labs) with the SONOFF ZBDongle-E, SMLIGHT SLZB-06M and Home Assistant Connect ZBT-1; and deCONZ with the ConBee III. CC2652 parts ending in “P” carry an amplifier rated up to 20 dBm against 5 dBm for “R” and “RB”. The ember driver needs current firmware: the EmberZNet page lists 7.4.x through 9.1.x and marks the older ezsp driver deprecated, so a stick from a drawer may need flashing first. For the Connect ZBT-1, Nabu Casa’s current recommendation is its Zigbee firmware rather than Thread, and the product page lists Zigbee2MQTT as compatible.

A 64-bit host with the Supervisor. The add-on route needs Home Assistant OS. The add-on installation page supports only aarch64 and amd64 and asks for at least a Raspberry Pi 4, because a Pi 3 “may cause instability due to its limited resources”. On Home Assistant Container, skip to the Docker section; OS vs Container explains why the Supervisor is the dividing line.

A USB extension cable. The range and stability guide says a 50 cm extension “is already enough to reduce the interference” and that an adapter next to a USB or HDMI port “can kill the radio signal entirely”; a USB 2 port instead of USB 3 also helps. Avoid coordinators attached over Wi-Fi: the adapters page warns the serial protocol “does not have enough fault-tolerance to handle packet loss or latency delays” on a wireless link.

Step 1: Install the Mosquitto broker

Zigbee2MQTT talks to Home Assistant over MQTT, so the broker comes first. Go to Settings > Apps > App store, install Mosquitto broker and start it. The Mosquitto app documentation tells you to create a dedicated MQTT user under Settings > People > Users, “not on Mosquitto’s Configuration tab”. Anonymous logins are not supported. The broker listens on 1883, and on 8883 once certificates are configured.

MQTT then appears as a discovered integration under Settings > Devices & services. Per the MQTT integration docs, Home Assistant “will automatically generate and assign a safe username and password” for that connection, and discovery is on by default with the homeassistant prefix. Accept it and leave the prefix alone; Zigbee2MQTT targets the default.

Step 2: Add the Zigbee2MQTT repository and install the app

Zigbee2MQTT is not in the default store. Following the add-on repository README: in the App store open the three-dot menu, choose Repositories, paste https://github.com/zigbee2mqtt/hassio-zigbee2mqtt, then Add and Close. Two apps appear. Zigbee2MQTT tracks released versions and is recommended for most users. Zigbee2MQTT Edge follows the dev branch; skip it unless a device you own is only supported there. Install the stable app, go to Info, press Start, wait a few seconds, then OPEN WEB UI.

Step 3: Onboarding, adapter and channel

The first start opens the onboarding page. Per the getting started guide, onboarding runs whenever no configuration.yaml exists, and its discovery step looks for serial and mDNS-reachable adapters. The README says that for most setups changing two fields is enough: select your adapter under Found Devices and fill in the Closest WiFi Channel. Press Submit and Zigbee2MQTT starts.

The Wi-Fi channel question exists so the Zigbee channel does not sit under your router. The network settings page defaults channel to 11 and advises the ZLL channels 11, 15, 20 or 25 “to avoid problems”. Get this right now: changing the channel later “might require re-pairing of some devices”, and changing network_key requires re-pairing all of them. pan_id, ext_pan_id and network_key start as GENERATE, which produces unique values on first start.

If discovery misses your stick, enter the persistent /dev/serial/by-id/... path rather than /dev/ttyACM0, which can change after a reboot; the adapter settings page shows the format, the adapter values (zstack, ember, deconz, zigate, zboss) and the tcp:// form for Ethernet coordinators. For the add-on, the MQTT server is mqtt://core-mosquitto:1883 with the user from step 1, per the app’s DOCS. If the app fails to start on a wrong adapter path, onboarding runs again next start, and Z2M_ONBOARD_FORCE_RUN=1 (a toggle in the add-on) forces it any time.

One quirk: the add-on cannot change its frontend port. The frontend page notes it is forced to 8099 for Home Assistant Ingress. Turn on Show in sidebar and you never need it.

Step 4: Let MQTT discovery populate Home Assistant

The Home Assistant integration page calls MQTT discovery “the easiest way” to integrate, and it needs homeassistant: enabled: true in Zigbee2MQTT’s configuration plus the MQTT integration from step 1. Every paired device then lands in Home Assistant’s device registry under the MQTT integration, and you can rename entities in the Home Assistant UI without a restart. Device-specific configuration can alter the discovery payload or hide a device entirely. For buttons and remotes, use MQTT device triggers; the legacy action sensor is marked deprecated.

Step 5: Pair the first device

In the frontend, press Permit join (All) in the top right. The pairing guide says this opens the network for 254 seconds and closes automatically; you can close it early. Every device resets differently, so open its entry on the supported devices page and follow the steps there. Success looks like Successfully interviewed '0x...', device has successfully been paired in the log. Keep permit join closed the rest of the time. If devices pair but later drop, work through Zigbee devices going unavailable before re-pairing anything.

Home Assistant Container: the Docker route

Without the Supervisor there is no App store, so Zigbee2MQTT runs as its own container against your own broker. The Docker installation page gives this compose file:

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0

Swap the devices line for your own by-id path and set TZ. To run rootless, add group_add: [dialout] and user: 1000:1000 as the docs describe. Onboarding appears on port 8080; point the MQTT server at your broker and add the MQTT integration in Home Assistant by hand with the same credentials. Docker Homelab’s first stack guide covers the bind-mount and restart-policy conventions this file relies on.

Back up before you have something to lose

The data directory (the add-on’s data path, or ./data in compose) holds configuration.yaml, the device database and the coordinator backup, and on a Supervisor install a Home Assistant backup can include app data. Only zStack and EmberZNet adapters support coordinator backups, which is what lets you move to a new stick without re-pairing. Treat network_key and channel as write-once, and enable the add-on’s watchdog option so a soft failure such as “adapter disconnected” restarts the app instead of leaving the mesh dark.

Related across the network

• Matter vs Zigbee vs Z-Wave: Which One to Build a Home On — matterhomelab.com
• Thread vs Zigbee: How the Two Meshes Differ — matterhomelab.com
• Does Matter Work Without Internet? What Stays Local and What Breaks — matterhomelab.com
• How Many Thread Border Routers Do I Need? A Count by House Size and Ecosystem — matterhomelab.com
• How Matter, Thread and Border Routers Fit Together — matterhomelab.com

Related on this site

• How to Install ESPHome on ESP32: Add-on, Docker or pip, Then the First USB Flash
• ZHA vs Zigbee2MQTT Explained: Same Radios, Different Software, and Which One to Run