Easily Backup & Migrate Your Zigbee Network!

Easily Backup & Migrate Your Zigbee Network!

How to Back Up and Migrate Zigbee2MQTT in Home Assistant

If your Zigbee network is stable, this is the moment to back it up.

Most people only think about Zigbee backups when they are about to replace a coordinator, move Home Assistant to new hardware, or recover from a failure. That is usually the worst possible time to learn how the process works.

This guide is for Home Assistant users running Zigbee2MQTT as an add-on. It covers the actual backup steps, what to save, and how to make life easier if you ever need to migrate to another machine or move to hardware like the Sonoff ZBDongle E - ZigBee USB 3.0 Dongle(E) Plus.

Why Zigbee backups matter

Many smart home users back up Home Assistant, but forget that the Zigbee network itself also has critical coordinator data behind it.

That matters because your Zigbee setup is not just a list of devices. It also includes network-level information that helps devices recognise the coordinator and continue working normally.

If you lose that data, you may end up having to:

  • re-pair devices one by one
  • rebuild device mappings
  • repair automations and scenes
  • troubleshoot missing or renamed entities
  • wait for the mesh to stabilise again

For larger Zigbee homes, that can be a major disruption.

What to back up in Zigbee2MQTT

For a Home Assistant add-on setup, keep these items:

  • the coordinator backup created inside Zigbee2MQTT
  • your Zigbee2MQTT configuration.yaml
  • the rest of your Zigbee2MQTT data folder, especially device and state files
  • a Home Assistant backup if your automations, dashboards, or entities depend on those Zigbee devices

The coordinator backup is the most important part, but it should not be the only part.

Why the coordinator matters so much

The coordinator is the heart of the Zigbee network. If it fails, gets replaced, or is moved to a new host, the success of the migration depends heavily on whether you have the right backup and whether the migration path is supported cleanly.

What to do before creating a Zigbee2MQTT backup

Before creating the backup:

  • make sure Zigbee2MQTT is running normally
  • confirm devices are online
  • avoid pairing or removing devices during the backup
  • do the backup before changing USB ports, hosts, firmware, or coordinators

If you are using the Home Assistant add-on, this is also a good time to note:

  • the Zigbee2MQTT add-on version
  • the serial device path currently set in the add-on
  • what coordinator you are currently using

If your network is already unstable, still take a backup, but understand it may include whatever state the network is currently in.

How to back up Zigbee2MQTT in Home Assistant

This is the part most people actually need.

1. Open the Zigbee2MQTT add-on in Home Assistant

In Home Assistant, go to Settings -> Add-ons -> Zigbee2MQTT.

Open the add-on and make sure it is running cleanly before you begin. If the add-on is constantly restarting or reporting coordinator errors, deal with that first if possible.

2. Create a coordinator backup

Open the Zigbee2MQTT web UI from the add-on, then go to the backup option for the coordinator and create a new backup.

Zigbee2MQTT stores this as coordinator_backup.json. Let the backup complete fully before doing anything else. Do not unplug the coordinator or restart Home Assistant halfway through.

If Zigbee2MQTT gives you the option to download the backup file, download it immediately and store it somewhere safe outside the device running Zigbee2MQTT.

Good places to keep it include:

  • your main computer
  • a NAS
  • a cloud drive you trust
  • a second backup location separate from the first

3. Back up the add-on data as well

The coordinator backup is not the whole story. Home Assistant users should also keep the add-on's Zigbee2MQTT data.

For Home Assistant users, the Zigbee2MQTT add-on data will usually include files such as:

  • configuration.yaml
  • state.json
  • database.db
  • coordinator_backup.json

In a Home Assistant setup, the easiest protection here is usually a full Home Assistant backup taken after the coordinator backup has been created.

That gives you two layers:

  • the coordinator backup from Zigbee2MQTT itself
  • the broader Home Assistant backup that includes add-on data and related configuration

Your exact file list may differ, but the goal is simple: keep the network backup and the surrounding configuration together.

4. Create a Home Assistant backup

In Home Assistant, go to Settings -> System -> Backups and create a fresh backup after you have created the Zigbee2MQTT coordinator backup.

If your setup matters, this is not a bad time to create a named backup so you know exactly why it exists.

For example:

  • Before Zigbee migration May 2026
  • Zigbee2MQTT working backup before dongle swap

If Home Assistant offers a backup location choice, save it somewhere other than the local machine when possible. If you use remote backup storage, make sure it has actually uploaded.

5. Save your serial settings

Open configuration.yaml and note the serial settings for your coordinator, especially the port and any adapter-related values.

This matters because when you restore or migrate, Zigbee2MQTT still needs to know how to talk to the coordinator.

If you are moving to a different coordinator, double-check that the configured adapter type and serial path still make sense on the new system.

6. Keep a dated copy of the coordinator backup file

Name the backup clearly so you know what it is later.

For example:

  • zigbee2mqtt-backup-2026-05-22
  • zbdongle-e-coordinator-backup-may-2026

If you ever need to restore quickly, clear naming helps more than people expect.

How to verify your Zigbee2MQTT backup

A backup is only helpful if you can identify it and trust it.

After saving it, check that:

  • the backup file downloaded successfully
  • the Home Assistant backup completed successfully
  • configuration.yaml is present
  • coordinator_backup.json exists in the Zigbee2MQTT data set if you are inspecting files directly
  • the backup is stored somewhere other than the same machine

If you only keep the backup on the same mini PC, Raspberry Pi, or server that runs Zigbee2MQTT, that is better than nothing, but not by much.

How to migrate Zigbee2MQTT to new Home Assistant hardware

If you are moving Zigbee2MQTT to a new machine or replacing a coordinator, keep the process boring. Boring is good here.

1. Make the backup before touching hardware

Do not unplug the old setup first. Create the backup while the current network is still alive.

2. Restore or rebuild Home Assistant first

If you are moving to a new Home Assistant machine, restore your Home Assistant backup first or rebuild the system to the point where add-ons can be installed again.

3. Connect the replacement coordinator

Connect the replacement coordinator and confirm Home Assistant can see it on the expected serial path.

4. Reinstall or open the Zigbee2MQTT add-on

Open the Zigbee2MQTT add-on in Home Assistant and check the serial configuration before starting it.

If you restored a Home Assistant backup, much of this may already be present, but still verify the serial path carefully under the add-on configuration.

5. Restore the coordinator backup if needed

If your migration path requires it, restore coordinator_backup.json inside Zigbee2MQTT and make sure the add-on is pointed at the correct coordinator device.

6. Start Zigbee2MQTT and test a few devices first

Do not assume the whole network is perfect just because the service starts.

Test:

  • one mains-powered router device
  • one battery sensor nearby
  • one battery sensor farther away
  • one or two real automations in Home Assistant

7. Let the mesh settle

After a migration, some devices may take a little time to choose better routes again. That is normal.

When a Zigbee2MQTT migration gets harder

Some restores go smoothly. Some do not.

Things get harder when you are:

  • moving between different coordinator chipsets
  • changing firmware without checking compatibility first
  • restoring partial backups instead of the full Zigbee2MQTT setup
  • changing the host, coordinator, software version, and configuration all at the same time

Zigbee2MQTT notes that coordinator backups are supported for zStack-based and EmberZNet-based adapters, which is important context before assuming every adapter migration will restore the same way.

If you can avoid stacking changes, avoid stacking changes.

Using a Sonoff ZBDongle-E with Zigbee2MQTT

If you are building around Zigbee2MQTT, a dedicated USB coordinator can make backup and migration planning much more straightforward than relying on a closed hub.

The Sonoff ZBDongle E - ZigBee USB 3.0 Dongle(E) Plus is one of the common options people use for that kind of setup.

Common Zigbee2MQTT backup mistakes

The most common mistake is thinking, "I will back it up when I get around to it," right before a hardware change.

Other common mistakes include:

  • keeping the only backup on the same machine as Zigbee2MQTT
  • assuming a Home Assistant backup automatically means the Zigbee coordinator backup is covered exactly how you expect
  • changing coordinators before checking whether the restore path is supported
  • renaming devices or restructuring automations during the migration

Final verdict

If you use the Zigbee2MQTT Home Assistant add-on, make a coordinator backup now, then create a fresh Home Assistant backup straight afterwards.

That one small job can save hours of re-pairing later.

If you are building around a USB coordinator, hardware like the Sonoff ZBDongle-E fits well with this kind of local-first Zigbee2MQTT setup.

For Zigbee coordinators, sensors, and smart home hardware, browse current products at The Smart Hut.

Related Products

Back to blog