When Home Assistant runs out of disk space, backups fail, updates stall, and the system becomes sluggish. This guide shows you how to analyze your storage usage and clean up leftover backups, bloated databases, and unused Docker files.
1. Analyze disk space in the settings
Start by getting an overview of your current disk usage.
In the web interface, go to Settings > System > Storage. Hover over the status bar to see how much space remains and whether backups, the database, or add-ons are consuming the most capacity. Anything under 10 percent free space is considered critical.
2. Delete outdated backups
Backups often take up multiple gigabytes and accumulate quickly.
Navigate to Settings > System > Backups. For older entries you no longer need, click the three-dot menu and select Delete. Alternatively, you can configure new backups to save directly to network storage (NAS via SMB/CIFS) to avoid filling up the local disk entirely.
3. Limit database retention in your configuration
The database can grow continuously, making it one of the most common causes of storage bloat.
Set a strict retention period in your configuration so historical data gets purged automatically.
Add the following block to your configuration.yaml:
recorder:
purge_keep_days: 10Under Settings > System > Repairs, you can also trigger a manual purge for the recorder integration if needed.
4. Clean up temporary backup files and Docker
Aborted backup jobs often leave behind massive temporary files that do not show up in the web UI.
Caution: Deleting files via the terminal interacts directly with the operating system. Run commands carefully.
Connect to your system via SSH. To remove orphaned temporary backups in the Supervisor directory, switch to that folder and delete the fragments:
cd /mnt/data/supervisor/tmp
rm -rf tmp*You can also clean up old, unused Docker images:
docker image pruneTo purge all unused images, containers, and networks, run:
docker image prune --all5. Clean up ESPHome files and Git
Microcontroller build artifacts and version control files can also grow unnoticed over time.
If you use the ESPHome add-on, click Clean all files to purge temporary compilation artifacts. If you version-control your configuration folder with Git, you can prune orphaned Git objects in the terminal like this:
git reflog expire --expire=now --all
git gc --prune=now --aggressiveDid it work?
Head back to Settings > System > Storage and check the bar: free space should have noticeably increased, and any low-disk-space warnings should disappear.
Troubleshooting
- Database does not shrink after purging: Depending on the database size, the cleanup process can take several minutes. Allow the operation to complete in the background.
- Disk space fills up again immediately: Check integrations like Frigate or security cameras that save recordings locally, and offload their storage to an external drive or network share.
With just a few steps, your system is cleaned up. As a next step, set up automated backups to an external network share to keep your local drive lean permanently.
Sources: Forum: Home Assistant Community, smarthome-assistant.info