restic stats
restic stats provides a detailed breakdown of the size and composition of your backups. It is essential for understanding how much physical storage your backups are occupying and how well Restic's deduplication is working.
While rsync tells you the size of the source, stats tells you the "True Cost" of your backups in the repository. It helps you justify retention policies or identify why storage is growing faster than expected.
Basic Syntax
restic stats [flags] [snapshotID...]
Statistical Modes
# Default mode: Summarize by snapshot
restic stats
# Raw Data: Show total unique bytes stored in the repo (Physical footprint)
restic stats --mode raw-data
# Restore Size: How much space is needed to restore the snapshots
restic stats --mode restore-size
# Files by Contents: Size of all files based on their unique content
restic stats --mode files-by-contents
Key Flags
| Flag | Description |
|---|---|
--mode MODE | Choose calculation mode: raw-data, restore-size, files-by-contents, blobs-per-file |
--host HOSTNAME | Only count stats for a specific host |
--tag TAG | Only count stats for snapshots with this tag |
--json | Output statistics in JSON format for prometheus/monitoring |
Practical Examples
1. Checking Total Repository Size (Physical)
This shows the actual bytes stored on your disk/S3 bucket after deduplication and compression.
restic stats --mode raw-data
2. Estimating Restore Space
If you need to restore the latest snapshot, how much free space do you need on the destination?
restic stats --mode restore-size latest
3. Monitoring Growth Trends via JSON
Pipe the output to scripts to track how your backups grow over time.
restic stats --mode raw-data --json | jq '.total_size'
4. Stats for a Specific Application
Filter by tag to see the footprint of your "databases" vs "media" snapshots.
restic stats --tag database
Understanding the Modes
| Mode | Use Case | Result Meaning |
|---|---|---|
raw-data | Billing & Capacity | Actual bytes used on the storage backend. |
restore-size | Capacity Planning | Total size if you were to "unzip" the snapshots to a disk. |
files-by-contents | Deduplication Audit | Shows how much "unique" content your files actually have. |
blobs-per-file | Internal Analysis | Counts chunks/blobs; useful for performance debugging. |
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
Confusing restore-size with raw-data | Panic over storage costs (restore size is usually much larger than raw data). | Use raw-data mode for billing/disk usage audits. |
| Running stats on huge cloud repos | Can be slow as it needs to load many index files. | Run stats on specific snapshots instead of the whole repo if possible. |
Ignoring stats after major deletions | Not realizing that space hasn't been freed yet. | Remember that stats only reflects the repo after a prune operation. |
Examples with Output
1. Raw Data (Billing View)
Command:
restic stats --mode raw-data
Output:
repository a7b2c9d opened successfully, password is correct
scanning...
Stats in mode raw-data compilation finished
Total Size: 1.240 GiB
2. Restore Size (The "Zip Bomb" View)
Command:
restic stats --mode restore-size
Output:
repository a7b2c9d opened successfully, password is correct
scanning...
Stats in mode restore-size compilation finished
Total Size: 50.812 GiB
3. Files by Contents (Deduplication Check)
Command:
restic stats --mode files-by-contents
Output:
repository a7b2c9d opened successfully, password is correct
scanning...
Stats in mode files-by-contents compilation finished
Total Size: 2.150 GiB
4. Stats for Specific Host
Command:
restic stats --host app-01 --mode raw-data
Output:
repository a7b2c9d opened successfully, password is correct
scanning...
Stats in mode raw-data compilation finished
Total Size: 840.100 MiB
5. Stats for Latest Snapshot Only
Command:
restic stats latest --mode restore-size
Output:
repository a7b2c9d opened successfully, password is correct
scanning...
Stats in mode restore-size compilation finished
Total Size: 5.100 GiB
What's Next?
Clean up old, expensive snapshots with restic forget and then restic prune.