Home Assistant backups are are tar archive files containing subarchives for various components and add-ons. Those subarchives are compressed and, since Home Assistant 2025.1, also forcefully encrypted.
While Home Assistant is a great home automation tool, the choice to use a custom archive format and custom encryption is just a horrible idea. You end up with broken padding in your backups and users unable to recover files from the backup using standard tools. Furthermore, not giving users control over compression and encryption makes integration with real backup systems and implementing a sane backup strategy difficult.
Modern backup systems like Borg Backup can deduplicate, compress and encrypt the data. Instead, the ad-hoc Home Assistant backup solution generates blobs that waste your throughput and storage. This makes an offsite backup or frequent snapshotting with long history difficult. Also, when those backup archives cannot be opened and analyzed using standard tools, partial recovery, backup validation or manual recovery are impossible.
Let's fix it!
Download the script, make it executable and run it. It was tested on Mac and Linux, but I see no reason why it wouldn't run on Windows.
./borgify-ha-backup.py -i automatic_backup_2025_1_4.tar -o decrypted_backup_2025_1_4.tar
The tool will ask you for your encryption key. You can also specify it via -p YOUR-ENCR-YPIO-NKEY-FROM-SETT-INGS.
If it complains about missing crypto libraries, run
pip3 install pycryptodome
You can validate that the produced tar archive (and other archives embedded in it) open in standard tools.
If you're lucky, you might even be able to use the standard Home Assistant mechanism to recover from the resulting archive. That's one of the project goals, but as for anything here - no guarantees.
Is your Home Assistant uploading backups to a NAS? Is your NAS Linux based? If so, consider running something like:
inotifywait -mqe close_write --format %f ~hass/backup/encrypted) | xargs -i \
./borgify-ha-backup.py -i ha-backup/encrypted/'{}' -o ha-backup/'{}' -D -p YOUR-ENCR-YPIO-NKEY-FROM-SETT-INGS
This would monitor ~hass/backup/encrypted for uploaded backups, automatically decrypt and decompress them into ~hass/backup and remove the encrypted original.
Run ./borgify-ha-backup.py -h to see all available options.
Read the comments in the source code or the source code itself to learn more about Home Assistant backup format horrors ;-)
- https://github.com/sabeechen/decrypt-ha-backup - this tool did not work for me, but I learned a lot from it.
- https://github.com/cogneato/ha-decrypt-backup-tool - this worked for me, but I wanted something that just converts the archive.