Restic retention: preview which backups will be deleted

Share
Laptop displaying code in a dark workspace
Contents

At a glance

Review a restic retention policy before deleting snapshots: identify the repository, inspect groups, run a dry run and check recovery after cleanup.

Write the recovery requirement first

A nearly full backup disk creates pressure to delete something quickly. Start by writing down what you still need to recover: yesterday's working folder, the version before a large migration, or records from a completed project. Those are different requirements. A policy that retains many recent snapshots can still discard the one older version you need.

This guide is for an existing restic repository you administer. It follows the stable restic 0.19.1 documentation checked on 16 November 2026. The examples use a local repository at /srv/restic-repo and a host called workstation; replace both with your real, verified values. For a shared business repository, agree the retention requirement with its owner before changing it. Keep a written exception for any investigation, contractual retention period or migration checkpoint. The intended result is a reviewed deletion list and a working recovery route, not simply a smaller disk-usage number. [1]

Identify the repository and its backup sets

Run restic version to identify the installed program, then check that you are using the expected executable and documentation. Distribution packages and official releases can differ. Avoid combining an unplanned software upgrade with the first destructive cleanup: changing two things makes an unexpected result harder to explain.

List the repository with restic -r /srv/restic-repo snapshots. Read the host, paths, dates and tags. Compare them with the backup job's actual configuration. A familiar directory name is not sufficient identification if several machines use that path. Restic applies retention separately to groups, using host and paths by default. Changing grouping changes which snapshots compete for the retained positions. Keep the existing grouping for this first review. If you cannot identify a group, stop before including it in a deletion policy and find the person or job that writes it. [1]

Record a baseline before changing retention

Save the snapshot listing and the intended policy in a private maintenance note. Include the repository location, installed version, time of inspection and the host being reviewed. Do not put repository passwords, cloud credentials or access tokens in that note. Names and paths can also reveal private information, so avoid posting the full output publicly.

Choose at least one recovery point that must survive, and record its snapshot ID. Check that it contains the expected folder using the documented listing commands. If an older snapshot is your only copy of a finished project, a general retention rule is not the right place to decide its fate. Arrange its continued retention or a separately verified archive first. This baseline also gives you something concrete to compare after maintenance, instead of relying on memory of how many backups used to exist. [1]

Preview one policy without deleting anything

For an illustrative policy, preview keeping seven daily, four weekly and six monthly recovery points for one host: restic -r /srv/restic-repo forget --host workstation --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --dry-run. The dry-run option prints the proposed actions without removing snapshots. Keep it present while adjusting the policy.

These counts are an example, not a recommendation for every dataset. Choose them from the recovery requirement and available storage. Daily and weekly retention uses calendar periods containing snapshots; it is not a promise that every recent calendar day has a successful backup. A laptop that was off for a week still has that gap. Check the actual dates in the output. If you change the host filter, grouping or counts, repeat the preview and review the new lists rather than treating the previous review as transferable. [1]

Read the retained and removed lists

Read both sides of the preview: what stays and what goes. Find the ID you marked as essential. Then examine the oldest retained date, the newest retained date and a few entries around an important change such as a computer replacement. Check every group printed by the command. A good total count can hide a problem in one small group.

For example, a workstation renamed after replacement may produce a different group from its predecessor. Decide explicitly whether both histories still matter. Do not remove grouping merely to make the output shorter. Likewise, several snapshots on one busy day do not provide several days of history. If the result disagrees with your written recovery requirement, change the proposed policy or preserve the exceptional snapshot before proceeding. Save the reviewed output with the maintenance note, and record why any unusually old recovery point remains. [1]

Separate snapshot removal from space reclamation

Restic separates two operations: forget removes snapshot records, while prune reclaims data no longer referenced by retained snapshots. The documented --prune option can combine them, but for a first maintenance run keeping the stages separate makes their outcomes easier to inspect. Removing a snapshot does not by itself guarantee an immediate fall in storage use.

When you are ready, rerun the exact reviewed forget command without --dry-run. Do not also change its filters or retention counts. Check its result before moving on. Schedule prune in a maintenance window: the documentation says it locks the repository and backups cannot complete during that operation. Coordinate with other jobs and keep the command's exit status and output. If a command fails, investigate the specific failure instead of repeatedly launching deletion commands or removing lock files because they appear inconvenient. [1]

What each maintenance result tells you

ResultWhat to checkNext decision
Dry runIDs, groups and actual retained datesApprove or revise the policy
Snapshot removalThe exact reviewed selection was usedInspect before reclaiming space
Repository checkWhich verification mode completedInvestigate errors or continue the recovery trial
Test restoreExpected content opens in a separate folderRecord the recovery result

Check the repository and a useful recovery point

After pruning, run the documented repository check and inspect its result. Restic distinguishes a normal check of repository structures from reading the stored data with --read-data. Choose the check appropriate to your maintenance plan and available time; do not report a basic check as a complete read of every stored file. For remote storage, account for the work and transfer involved.

Then restore a representative retained file or folder to a separate destination and open the result. Use a specific retained snapshot ID so the exercise tests the recovery point you intended. Keep production files untouched during this trial. Compare the restored content with what you expected, and note the result. Our separate backup-restore guide covers that practical verification in more detail. Successful cleanup and successful recovery answer different questions; record both before declaring maintenance finished. [2][3]

Put the reviewed rule into the schedule

Only automate the policy after the preview and recovery checks make sense. Put the verified repository, filters and retention options into the existing maintenance job, with output and failures recorded somewhere you actually review. Keep backup creation and cleanup at times that do not overlap. Record who can change retention and where the exception list is kept.

Revisit the policy when a machine is renamed, a folder moves, the backup frequency changes or a project ends. These are concrete reasons to run another preview. Monitor the dates of successful backups as well as free space: a tidy repository with no recent recovery point does not meet the original requirement. Preserve the maintenance note and the recovery result, then remove temporary restored files when they are no longer needed. That closes this cleanup without silently turning a one-off command into an unreviewed permanent rule. [1]

Frequently asked questions

Does forget immediately free all the space?

Snapshot removal and reclaiming unreferenced data are separate operations. Review the prune stage and its result rather than assuming deletion of a snapshot means the storage has already shrunk. [1]

Is seven daily backups always seven calendar days?

Read the actual retained dates. Retention periods containing snapshots do not fill gaps when the backup job did not run. [1]

Can I delete a repository lock to make cleanup continue?

First determine which operation owns the lock and whether it is still running. A lock is not, by itself, evidence that it is stale. [1]

Evidence & sources

Source record: · Checked:

Record limits · Evergreen maintenance workflow based on restic 0.19.1 documentation checked on 16 November 2026. Retention counts are examples; review steps are editorial recommendations.

  1. [1]Source reported

    Restic forget supports a dry run and applies retention to snapshot groups.

    Supporting excerpt: Restic snapshot retention and pruning

    Original quotation

    not remove anything
    Restic snapshot retention and pruning ↗

    Source language: EN · Captured Nov 16, 2026

  2. [2]Source reported

    Restic distinguishes checking repository structures from reading stored data.

    Supporting excerpt: Restic: repository checks

    Original quotation

    verify the integrity of the pack files
    Restic: repository checks ↗

    Source language: EN · Captured Nov 4, 2026

  3. [3]Source reported

    Restic can restore a specified snapshot to a separate target.

    Supporting excerpt: Restic: restoring from backup

    Original quotation

    restore the contents
    Restic: restoring from backup ↗

    Source language: EN · Captured Nov 4, 2026