restic prune

restic prune is the garbage collection command for Restic. While forget removes snapshot entries, prune scans the repository for data chunks (blobs) that are no longer referenced by any existing snapshot and physically deletes them from the storage backend.

Quick Summary

forget is the "Delete" key in your email app; prune is "Empty Trash." Without prune, your repository will continue to grow even if you delete snapshots.

Basic Syntax

restic prune [flags]

Automation Recommendation

You rarely need to run prune as a standalone command. It is most commonly executed as part of a forget operation:

restic forget --keep-last 7 --prune

Key Flags

Flag	Description
--max-unused N	Only prune if at least N% of the repo is unused (e.g., 5%)
--max-repack-size SIZE	Limit the amount of data to repack during pruning
--dry-run / -n	Calculate how much space would be freed without deleting anything
--repack-cacheable-only	Only repack data that is also in the local cache
--compression MODE	Set compression for repacked data: auto, off, max

How Pruning Works (The Workflow)

1. Index Loading: Restic loads all indexes to see what data is stored.
2. Referenced Blob Search: Restic scans every existing snapshot to see which data chunks are "active."
3. Unused Detection: Any chunk NOT found in step 2 is marked for deletion.
4. Repacking: Since Restic stores many small chunks in larger "Pack" files, if a pack file has only some unused chunks, Restic downloads it, removes the junk, and uploads a new, smaller pack (this is "repacking").
5. Physical Deletion: Old pack files and metadata are deleted from the storage.

forget vs prune

behavior	forget	prune
I/O Heavy	No (Quick metadata update)	Yes (Heavy Read/Write)
Frees Space	❌ (Disk usage stays same)	✅ (Physical deletion)
Snapshots	Removes IDs from history	Removes data from backend
Risk	Can be undone via recover	Permanent data loss

Practical Examples

1. Manual Cleanup After Large Deletions

If you just manually deleted 50 old snapshots, run a standalone prune to reclaim space.

restic prune

2. Throttled Pruning (Bandwidth Saving)

If you have a 10TB repo on S3, repacking everything can be expensive. Use --max-unused to only prune when it's worth the cost.

# Only run prune if more than 10% of the repo is garbage
restic prune --max-unused 10%

3. Maximum Compression during Prune

Convert an old V1 or uncompressed repo to high compression during the prune process.

# Requires Repo V2
restic prune --compression max

Common Pitfalls

Pitfall	Consequence	Prevention
Pruning during Backup	Restic locks the repo; backups will fail.	Ensure prune is scheduled during a quiet window.
Interrupted Prune	Leftover temporary files and potentially inconsistent indexes.	Run restic unlock and then restic check if a prune crashes.
High Cost on Cloud	S3 API requests and egress fees during repacking.	Use --max-unused to avoid frequent repacking for minor gains.

Examples with Output

Examples with Output

1. Standard Prune (Cleanup)

Command:

restic prune

Output:

repository a7b2c9d opened successfully, password is correct
loading all snapshots...
finding used blobs...
searching for unused blobs...
unused blobs: 1250 (45.210 MiB)
finding blobs that need repacking
repacking 2 packs...
deleting 2 old packs...
done

2. Dry Run (Preview)

Command:

restic prune --dry-run

Output:

repository a7b2c9d opened successfully, password is correct
loading all snapshots...
unused blobs: 500 (10.5 MiB)
3 packs would be repacked
5 packs would be deleted
10.5 MiB would be freed

3. Conditional Prune (Max Unused 10%)

This command will exit without pruning if less than 10% of the repo is junk. Command:

restic prune --max-unused 10%

Output:

repository a7b2c9d opened successfully, password is correct
loading all snapshots...
unused blobs: 20 (500 KiB)
repo is 99% used, max unused is 10%, strictly resizing not needed

4. Prune with Max Compression

This re-writes existing packs to use stronger compression (slow but frees space). Command:

restic prune --compression max

Output:

repository a7b2c9d opened successfully, password is correct
loading all snapshots...
repacking all packs...
[75%] repacking packs...
deleting 50 old packs...
done
saved 1.2 GiB space through compression

5. Prune Specific Data only (Repack small packs)

Command:

restic prune --max-repack-size 50M

Output:

repository a7b2c9d opened successfully, password is correct
loading all snapshots...
limiting repack to 50 MiB...
repacking 3 packs...
deleting 3 old packs...
done

What's Next?

Ensure your repo is still healthy after pruning with restic check.