Smart Home

ZHA vs Zigbee2MQTT: pick and migrate

Choose between ZHA and Zigbee2MQTT and migrate cleanly — the three operations people conflate (coordinator swap, software switch, asymmetric ZHA↔Z2M) and where re-pairing is unavoidable.

Problem summary

The 'which is better' question is saturated; the real trouble is migration, where three different operations get conflated. A same-software coordinator swap keeps your devices (both ZHA and Z2M support it; ZHA even has a built-in cross-vendor Migrate Radio wizard). A ZHA↔Zigbee2MQTT software switch is hard — the supported answer is re-pair, and the 'no-re-pair' community scripts are fragile and unsupported. The low-risk path is a second coordinator and a gradual move.

Operator snapshotEvidence first

First proof

Name the operation: coordinator swap, or stack switch (ZHA↔Z2M)?

Screen to open

ls -l /dev/serial/by-id/

Expected signal

You know whether re-pairing is avoidable.

Stop boundary

If you try a script, back up first and expect it may fail.

Layer path

1The 'which is better' debate is saturated; the real difficulty is migration, where three distinct operations get conflated.

2A same-software coordinator swap keeps your devices — both ZHA and Zigbee2MQTT support it, and ZHA has a built-in Migrate Radio wizard that works even across chip vendors.

3A ZHA↔Zigbee2MQTT software switch is hard: the supported answer is re-pair, and the 'no-re-pair' community scripts are unsupported and fragile (they broke on a 2026 Home Assistant template change).

4The low-risk path is a second coordinator: run the new stack in parallel and move devices gradually (mains-powered routers first, then battery end devices).

Runbook

Step-by-step runbook

Start here. Do each check in order, compare it to the expected result, and stop when the evidence explains the failure or the safe stop point applies.

Classify the migration

Check: Decide coordinator swap vs ZHA↔Z2M stack switch.

Expected result: You know whether re-pairing is needed.

If not: Don't treat a software switch as a simple radio change.

For a swap, use the built-in path

Check: Run ZHA's Migrate Radio wizard (or Z2M's supported swap).

Expected result: Devices stay paired on the new coordinator.

If not: Keep the old radio until the new one is verified.

For a stack switch, go parallel

Check: Add a second coordinator and run the new stack alongside.

Expected result: You can move devices at your own pace.

If not: Pair mains-powered routers first, battery devices last.

Avoid the fragile shortcut

Check: Skip unsupported no-re-pair scripts unless you've backed up and accept the risk.

Expected result: You don't corrupt the Zigbee database mid-migration.

If not: The parallel approach is the safer route.

Verify and decommission

Check: Confirm devices respond on the new stack/radio, then retire the old.

Expected result: The migration is proven before cleanup.

If not: If a device won't move, re-pair just that one.

Decision tree

If: You just want a better/newer radio.

Then: Coordinator swap, same software.

Action: Use ZHA's Migrate Radio wizard or Z2M's supported swap — devices stay paired.

If: You want to switch ZHA to Zigbee2MQTT.

Then: Software switch — re-pairing is the supported answer.

Action: Re-pair, or run Z2M alongside ZHA and move devices gradually.

If: You're tempted by a no-re-pair conversion script.

Then: Unsupported and version-fragile (broke on a 2026 API change).

Action: Use the parallel-coordinator approach instead for safety.

Safe stop: If you try a script, back up first and expect it may fail.

If: You need more than one Zigbee network.

Then: ZHA can't; Z2M can (multiple instances).

Action: Choose Zigbee2MQTT for multi-network setups.

Evidence

Evidence table

Symptom	Evidence to collect	Likely layer	Next action
Want to change radios, keep devices.	Whether it's a same-software swap and both adapters are supported.	Coordinator swap	Use the Migrate Radio wizard / supported Z2M swap.
Want to leave ZHA for Z2M.	Whether you accept re-pairing or will run parallel stacks.	Stack switch	Re-pair or move gradually with a second coordinator.
Tried a no-re-pair script and it errored.	Script/version compatibility (e.g. 2026 template change).	Unsupported migration script	Fall back to re-pairing or parallel coordinators.
Need multiple Zigbee networks.	ZHA single-network limit vs Z2M multi-instance.	Topology requirement	Pick Z2M for multiple networks.

Reference

Commands and settings paths

Find both coordinators' paths

ls -l /dev/serial/by-id/

Where: On the Home Assistant host.

Expected: Each coordinator appears with a stable by-id name.

Failure means: Missing entries mean the adapter isn't connected/passed through.

Safe next step: Use the by-id path in ZHA/Z2M config, not /dev/ttyACM0.

Use ZHA's Migrate Radio wizard

Settings > Devices & Services > ZHA > (kebab) > Migrate Radio

Where: In the Home Assistant UI.

Expected: ZHA backs up and restores the network onto the new coordinator.

Failure means: If it errors, the target adapter may be unsupported.

Safe next step: Pick a supported adapter; keep the old one until verified.

Stand up Z2M in parallel (stack switch)

Add a second adapter; configure Zigbee2MQTT (adapter: ember, baud per device)

Where: In the Z2M add-on/container config.

Expected: Z2M runs alongside ZHA on the second radio.

Failure means: Wrong adapter/baudrate stops Z2M from starting.

Safe next step: Use the device-correct adapter/baud; move devices gradually.

Hardware boundary

Hardware and platform boundary

Change only when

Buy a second supported coordinator (e.g. Connect ZBT-2) when switching stacks or radios — it enables a gradual, low-risk move and a clean coordinator swap.

Evidence that matters

A supported adapter (ZBT-2/ZBT-1, TI zstack, Silabs ember), referenced by by-id, and a backup before you start.

Evidence that does not matter

Brand loyalty between ZHA and Z2M — pick by needs (multi-network, add-on workflow), and migrate by operation type, not hype.

Avoid

Promising yourself a no-re-pair ZHA→Z2M switch via an unsupported script (it broke on a 2026 HA change) instead of re-pairing or going parallel.

Related tool

Use the linked tool to turn this runbook into a guided check for your exact setup.

Device setup troubleshooter

Last reviewed

2026-06-03 · Reviewed by HomeTechOps. Built from 2026-06 research verified against home-assistant.io ZHA docs and Zigbee2MQTT migration docs; the differentiator is separating the three conflated operations (coordinator swap vs stack switch vs ZHA↔Z2M asymmetry) and flagging the no-re-pair scripts as unsupported/fragile. SkyConnect is the legacy name for ZBT-1.

Sources/assumptions

Assumes a Zigbee network on ZHA or Zigbee2MQTT with a supported coordinator (Connect ZBT-2/ZBT-1, TI zstack, or Silabs ember); SkyConnect is the legacy name for ZBT-1.
A same-software coordinator swap can avoid re-pairing; a ZHA↔Z2M software switch generally cannot, and any 'no-re-pair' script is community/unsupported and version-fragile.
Adapter/baudrate values (e.g. ember at 460800) are device-specific; chip-family support lists change — verify against current docs.

Source-backed checks

HomeTechOps turns official docs and conservative safety rules into a shorter runbook. These links are the source trail for the page direction.

Home Assistant: Zigbee Home Automation (ZHA) integrationUsed for ZHA's automatic Zigbee network backup, the built-in Migrate Radio wizard (cross-vendor), and the no-re-pairing-when-the-same-radio-moves fact for migrations.Zigbee2MQTT: Connecting a new coordinator / migrationUsed for the Z2M coordinator-swap mechanics (supported adapters, copy the IEEE address, restore the network backup) and why a ZHA↔Z2M software switch is harder than a same-software coordinator swap.Home Assistant: Introducing Connect ZBT-2Used for the radio naming truth — SkyConnect was renamed Connect ZBT-1, which ended production Nov 2025; the current Zigbee/Thread adapter is Connect ZBT-2 (Zigbee OR Thread, not both at once).

Diagnostic rule

1. Check the simplest signal first.
2. Change one thing at a time.
3. Confirm the layer (radio, IP, app) before deep config.
4. Stop when the evidence says the risk moved.

FAQ

Can I migrate from ZHA to Zigbee2MQTT without re-pairing everything?

Officially, no — the supported answer for a ZHA→Zigbee2MQTT software switch is to re-pair. Community scripts can convert the ZHA database without re-pairing, but they're unsupported and have broken on Home Assistant API changes (e.g. an early-2026 template change), so treat them as fragile. Z2M→ZHA is reportedly simpler. If you just want a better radio, that's a coordinator swap (below), not a software switch.

How do I move to a new Zigbee coordinator without losing devices?

Stay on the same software and do a coordinator swap. ZHA has a built-in Migrate Radio wizard that backs up and restores the network and can even move across chip vendors; Zigbee2MQTT supports it too if the adapter is supported (copy the IEEE address and restore the network backup). That keeps devices paired. It's the software switch (ZHA↔Z2M), not the radio change, that forces re-pairing.

What's the lowest-risk way to switch stacks?

Run two coordinators in parallel. Add a second dongle, stand up the new stack (e.g. Zigbee2MQTT) alongside ZHA, and move devices at your own pace — pair the mains-powered routers first, then the battery end devices. ZHA and Z2M can run simultaneously on one Home Assistant with two radios. It's more setup but avoids a risky big-bang cutover.