A Home Assistant backup is only useful if three things survive the day your server dies: the backup file, the key that decrypts it, and the username and password you had when it was made. When a restore fails, one of those three is usually missing, and very often it is the file itself, because the only copy sat on the SD card or SSD that just gave up.

Since the 2025.1 release, Home Assistant has a backup system designed around exactly this: scheduled backups, automatic cleanup, encryption by default and extra backup locations provided by integrations. Restoring works on every installation type, including Docker. Here is how to set it up so that a restore actually works when you need it.

What a backup contains

A backup is a compressed .tar archive, encrypted, stored by default in the local /backup directory. A full backup includes these folders:

  • config: configuration, automations, dashboards and, unless you moved it, the recorder database;
  • share;
  • addons: only apps you installed manually or wrote yourself, not those from the store;
  • ssl;
  • media.

"Apps" is the current name for what Home Assistant used to call add-ons. Installed apps can be included too, and a partial backup is any selection of the folders and apps above.

Two things follow from this list. The backup holds the keys to the whole house: in its post on the new backup system, the Home Assistant team points out that a backup contains the access credentials for every integrated device and the history of how you live. Treat the file the way you would treat a password database. The second point is size. The docs recommend leaving media and the share folder out of regular backups, because a large backup also takes longer to restore.

Before the first backup, check how big the database is. Go to Settings > System > Repairs, open the three dots menu, choose System information and look for Estimated Database Size (MiB) in the Recorder section. By default the recorder keeps 10 days of history. If you raised that, the database may well be the largest thing in the archive.

The emergency kit is the part people lose

When you set up backups for the first time, Home Assistant generates an encryption key and offers to download it as an emergency kit. Without that key an encrypted backup cannot be restored at all. Nabu Casa does not keep a copy and cannot help decrypt a backup if the key is gone.

Keep the kit outside Home Assistant. A password manager is a good place, and a printed copy in a drawer does no harm. A kit that exists only on the server you are trying to protect is no kit at all.

A few details catch people out:

  • One key encrypts all backups. If you replace it (Configure automatic backups, then Change under Encryption key), new backups use the new key and older ones still need the old one. Download the old kit before changing the key and write down which backups it belongs to.
  • As long as Home Assistant still runs and you have not changed the key, you can download the kit again from the backup settings.
  • A backup downloaded from the backups page is decrypted on the fly, so you can open it with an ordinary archive tool. A file copied straight from the backup folder, for example over the Samba app, stays encrypted.

Setting up automatic backups

  1. Go to Settings > System > Backups and select Set up backups.
  2. Download the emergency kit and put it somewhere safe.
  3. Pick a schedule. The docs recommend daily. System optimal picks a time within a window shown in the UI, Custom lets you choose the hour. Choose a time when every backup location is reachable, otherwise the backup to the missing location fails.
  4. Decide whether Home Assistant should back up automatically before updates. This only sets the default, and you can still change it for each update. On a large installation the update will start later, after the backup finishes.
  5. Set how many backups to keep. Older automatic backups are deleted. With daily backups and a limit of 7, anything from 8 days ago or older goes. Backups you create by hand are left alone by this cleanup.
  6. Choose what to include. This is where you switch off media and share if you do not need them.
  7. Choose the locations, described below.

If you accept the wizard's recommended settings, Home Assistant makes a backup every night, keeps three and uploads them to every available location.

Where to keep the copies

The Home Assistant team recommends the 3-2-1 rule: three copies of your data, on two different types of media, one of them off-site. Their example is a lightning strike that destroys both the Home Assistant machine and the NAS standing next to it. In practice that means local storage plus at least one other system, and ideally one copy outside the house.

You enable locations in Configure automatic backups under Locations:

  • Local storage on the Home Assistant machine itself. Fine as one of the copies, useless as the only one.
  • Network storage (NAS). On Home Assistant OS, go to Settings > System > Storage, select Add network storage, choose NFS or CIFS (Samba/Windows, version 2.1 or newer) and set the usage to Backup. The first share added with this usage becomes the default local backup location. This requires Home Assistant OS 10.2 or newer.
  • Synology DSM. The Synology DSM integration can use a shared folder from File Station as a backup location without adding the NAS as a network drive (DSM 6.0 or newer). The DSM user needs the File Station application permission and read/write access to that folder.
  • Google Drive and OneDrive. Both integrations can only reach their own folder: a Home Assistant folder in Google Drive, and an app folder in OneDrive that is often called Graph instead of Home Assistant because of an issue in Microsoft's API. Removing the Google Drive integration does not delete its folder, so clean it up by hand.
  • Home Assistant Cloud. Subscribers can store one backup of up to 5 GB at no extra cost. Only the latest backup uploaded there is kept, and it is always encrypted with AES-128. Nabu Casa has announced that the service is being renamed Home Assistant Link and plans to make the new name official in the 2026.12 release. Until then the UI and docs use the old name.

For every location except Home Assistant Cloud, the cog next to it switches encryption on or off. Leave it on for anything that leaves your network.

If the built-in schedule does not fit, the backup.create_automatic action starts a backup with your automatic backup settings from any automation. The docs give an example: an automation that powers on a NAS, waits until it is online and only then starts the backup. On Home Assistant OS you can also use the command line: ha backups new --name nameofbackup creates a backup and ha backups list lists existing ones.

Get a notification when a backup fails

A schedule nobody checks can stop working without anyone noticing, for instance when the NAS was asleep at 4 a.m. The Backup integration provides an event entity, event.backup_automatic_backup, whose event_type attribute is completed, in progress or failed, and whose failed_reason attribute explains a failure. There are also sensors for the last successful and last attempted automatic backup. The documentation includes this automation, which sends a notification to your phone when a backup fails:

alias: "Backup failed"
triggers:
  - trigger: state
    entity_id:
      - event.backup_automatic_backup
conditions:
  - condition: state
    entity_id: event.backup_automatic_backup
    attribute: event_type
    state: failed
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_device
    data:
      title: "Automatic backup failed"
      message: >-
        The last automatic backup failed due to
        {{ state_attr('event.backup_automatic_backup', 'failed_reason') }}

Replace notify.my_device with your own notification entity.

Restore once before you have to

The Home Assistant team lists testing among the parts of a sound backup strategy, and a restore is much easier to learn on a quiet afternoon than during an outage. At the very least, download a backup from time to time and open it to check that it contains what you expect. Better still, restore it onto a spare machine or a virtual machine.

There are two ways to restore.

On the running system. Go to Settings > System > Backups, select the backup, choose what to restore and select Restore. Whatever you select overwrites the current state, and Home Assistant restarts when it is done.

During onboarding on a fresh installation. This is also how you move to new hardware, and the target can be a different type of device, for example a mini PC instead of a Raspberry Pi.

  1. If you are moving to a new machine, plug in your radios first, such as a Z-Wave stick or a Zigbee adapter.
  2. On the welcome screen, choose Upload backup and select the file, or choose Home Assistant Cloud and sign in.
  3. Select the parts to restore and enter the encryption key from the emergency kit.
  4. Select Restore backup and wait. Do not refresh the page: the system is shut down, wiped and reinstalled from the backup, and a refresh only shows a "Not found" message.
  5. Log in with the username and password that were valid when the backup was made, not ones you set later.

Check the storage before a migration. The new device needs more free space than the Disk used value on the old one, which you will find under Settings > System > Repairs > System information, in the Home Assistant Supervisor section. The size of the backup file tells you nothing about the size of the installation. A large restore can take around 45 minutes, because Home Assistant Core and all apps are reinstalled.

After the restore, battery-powered devices may show as unavailable until they wake up, network storage may need to be connected again, and if you had certificates configured directly in the http integration, the instance will answer only on https://. If the new machine has a different Zigbee radio than the old one, you also have to migrate the Zigbee network to it.

Mistakes that make a backup worthless

  • Backups only on the device itself. When the disk dies, every backup on it dies too.
  • Emergency kit kept inside Home Assistant, or never downloaded. Encrypted backups cannot be opened without it.
  • Key changed, old kit thrown away. Backups made before the change can no longer be decrypted once Home Assistant has stopped using the old key.
  • Home Assistant Cloud as the only off-site copy of a large installation. It holds one backup of up to 5 GB. Trim media, share and the database, or add another location.
  • Network storage offline at backup time. The backup to that location fails. Move the schedule, or wake the NAS in an automation and start the backup with backup.create_automatic.
  • Forgotten password. A restore brings back the users from the time of the backup, so you need the login from back then.