In recent versions, Home Assistant has renamed the former Services to Actions. Please pay attention to this interface change.
Below are three methods, from simple to advanced. Beginners are advised to start with the first one.
Method 1
.
Method 1: Manual Cleanup (Safest, Most Recommended)
This method uses Home Assistant’s built-in tools to clean up old data. It will not delete your configuration by mistake, and it is suitable when you are running low on disk space and want to free it up right away.
- Open Developer Tools: Click Developer Tools in the left sidebar.
- Switch to the Actions tab: In the top menu, click Actions (called Services in older versions).
- Search for the purge action: Type recorder.purge in the search box and click Recorder: Purge.
- Configure the purge parameters:
- Keep days: enter how many recent days of history you want to keep. For example, entering 7 keeps only the last 7 days and deletes everything older.
- Repack: make sure to check this box!
- Explanation: if you do not check it, the data is only marked as deleted but the database file usually does not shrink (similar to the Recycle Bin on a computer). Only with this checked will the file actually be compacted and disk space released.
Apply filter: generally leave it unchecked.
- Explanation: if you only want to delete the history of a few specific sensors, you can check this and add the entity IDs below. But to free up space you usually purge everything, so leave it unchecked.
Run the cleanup:Click the green Perform Action button.
- Note: after clicking, the interface will not clearly say Done, but the work has already started in the background. If your database is large (several GB, for example), this process may take several minutes or longer. Please be patient and do not click repeatedly.
Method 2: Automatic Maintenance (Once and For All)
If you do not want to delete manually every time, you can edit the configuration file and let Home Assistant clean up expired records automatically every day.
Install / open File Editor:Make sure you have installed the File Editor or Studio Code Server add-on to edit configuration files.
Edit:Open the /config/configuration.yaml file.
Add / modify the Recorder configuration:Find the recorder: field in the file (add it on a new line if it does not exist). Copy the following content:
recorder: # 每天自动清理，只保留最近 10 天的数据（根据你的硬盘大小调整，SD卡建议 5-7 天）
purge_keep_days: 10
# 开启自动重组，确保存储空间被真正释放
auto_repack: true
# (可选) 如果你想彻底屏蔽某些传感器不记录历史，可以在这里排除
exclude:
domains:
- automation
# 不记录自动化的触发历史[()][()]
- update
# 不记录更新实体的历史
entities:
- sensor.date
# 不记录日期变化[()][()]
- sensor.time
# 不记录每分钟的时间变化（这个非常占空间！）```[()][()]Restart the system:After saving the file, go to Settings -> System -> and click Restart Home Assistant in the top right corner so the configuration takes effect.
Method 3: Nuclear Cleanup (Full Reset)
If your database file (home-assistant_v2.db) is already corrupted, or has grown to tens of GB and the methods above do not work, you can simply delete it. The consequence is that you lose all history charts (they become blank), but device configurations and automations are not lost.
- Stop Home Assistant:
- Go to Developer Tools -> YAML and click Check Configuration to make sure there are no errors.
- You need to use SSH or the host terminal. Enter the command: ha core stop (for HAOS).
- Beginner alternative: simply click Restart in the web interface and, in the instant before the restart completes (when the web page loses connection), carry out step 2 — but this is not safe enough. Installing the Terminal & SSH add-on is recommended.
Delete the database file:Use File Editor or Samba to access the /config folder.Find the file named home-assistant_v2.db and delete it directly.
Restart the power / system:Unplug the power and plug it back in, or enter ha core start in the terminal.After startup, the system will automatically create a brand-new empty database file of just a few KB.
How to verify that space has been freed?
- Before cleanup: go to Settings -> System -> Storage and check the current disk usage.
- After running Method 1 or Method 3: wait about 5-10 minutes (let the system finish compacting), then return to the Storage page and you will see the usage drop noticeably.
