rustic — Fast, restic-compatible Backups in Rust

rustic is a backup tool written in Rust that produces fast, encrypted, deduplicated snapshots – while staying fully compatible with existing restic repositories, so you can move between the two tools seamlessly. On top of what restic offers, rustic adds TOML configuration profiles, native cold-storage support and richer retention rules. This guide walks you through the commands you reach for daily: initialising a repository, creating backups, browsing snapshots, restoring data and pruning old states.

Repository Initialization

rustic init -r <repo> — Initialize a new local repository at the given path.

rustic init -r /mnt/backup/myrepo

rustic -r sftp:<user>@<host>:<path> init — Initialize a repository on a remote server via SFTP.

rustic -r sftp:user@server.com:/backup/repo init

rustic -r opendal:s3 -o s3.bucket=<bucket> -o s3.region=<region> init — Initialize an S3-compatible repository via the OpenDAL backend.

rustic -r opendal:s3 -o s3.bucket=my-backups -o s3.region=eu-central-1 init

rustic -r rclone:<remote>:<path> init — Initialize a repository via rclone (uses any rclone-configured backend).

rustic -r rclone:gdrive:backups/rustic init

rustic init --set-compression <level> — Initialize with a specific compression level (-1 to 22, default uses zstd auto).

rustic init -r /mnt/backup/repo --set-compression 3

Configuration Profiles

rustic -P <profile> <command> — Run a command using a named profile from ~/.config/rustic/.toml or /etc/rustic/.toml.

rustic -P daily backup

[repository] in <profile>.toml — Profile section defining repository, password-file, no-cache, and other repo-wide options (TOML).

[repository]
repository = "/mnt/backup/repo"
password-file = "/etc/rustic/pw"

[backup] / [[backup.snapshots]] in <profile>.toml — Pre-configured backup sources with sources, tags, excludes — invoked via 'rustic backup' without arguments.

[[backup.snapshots]]
sources = ["/home", "/etc"]
tag = ["daily"]

[forget] in <profile>.toml — Default retention rules — applied by 'rustic forget' without flags.

[forget]
keep-daily = 7
keep-weekly = 4

Creating Backups

rustic -r <repo> backup <path> — Back up a file or directory to the repository.

rustic -r /mnt/backup/repo backup /home/user

rustic -r <repo> backup <path1> <path2> — Back up multiple paths in a single snapshot.

rustic -r /mnt/backup/repo backup /home/user /etc

rustic backup --tag <tag> <path> — Add one or more tags to the snapshot for filtering and retention.

rustic backup --tag daily --tag web /var/www

rustic backup --label <label> <path> — Set a label on the snapshot (useful to group snapshots from different sources).

rustic backup --label production /var/www

rustic backup --glob <pattern> <path> — Exclude files or directories matching the given glob pattern.

rustic backup --glob '!**/node_modules' /home/user/projects

rustic backup --glob-file <file> <path> — Read include/exclude glob patterns from a file (one per line, prefix '!' to exclude).

rustic backup --glob-file ~/.rusticignore /home/user

rustic backup --files-from <listfile> <path> — Read additional files and directories to back up from a file.

rustic backup --files-from /etc/rustic/includes.txt

rustic backup --as-path <virtual-path> <path> — Store the backup under a different (virtual) path inside the snapshot. Useful for renamed sources.

rustic backup --as-path /home/user /mnt/restore/home/user

rustic backup --json <path> — Emit machine-readable JSON progress output for scripting and monitoring.

rustic backup --json /home/user | jq .

rustic backup --dry-run <path> — Show what would be backed up without writing to the repository.

rustic backup --dry-run /home/user

Listing & Inspecting Snapshots

rustic -r <repo> snapshots — List all snapshots in the repository.

rustic -r /mnt/backup/repo snapshots

rustic snapshots --filter-tag <tag> — List snapshots filtered by tag.

rustic snapshots --filter-tag daily

rustic snapshots --filter-host <hostname> — List snapshots from a specific host.

rustic snapshots --filter-host webserver01

rustic snapshots --json — Output snapshot list as JSON for scripting.

rustic snapshots --json | jq '.[].id'

rustic ls <snapshot-id> — List files inside a specific snapshot.

rustic ls a1b2c3d4

rustic ls latest — List files inside the most recent snapshot.

rustic ls latest

rustic diff <snapshot1> <snapshot2> — Show file differences between two snapshots.

rustic diff a1b2c3d4 latest

rustic cat <type> <id> — Print the raw decoded content of a repository object (snapshot, tree, blob, config).

rustic cat snapshot a1b2c3d4

Restoring Data

rustic restore <snapshot-id> <target> — Restore a full snapshot to the given target directory.

rustic restore a1b2c3d4 /tmp/restore

rustic restore latest <target> — Restore the latest snapshot.

rustic restore latest /tmp/restore

rustic restore latest:/<path> <target> — Restore only a sub-path from the latest snapshot.

rustic restore latest:/home/user/Documents /tmp/restore

rustic restore --glob <pattern> <snapshot> <target> — Restore only files matching a glob pattern (prefix '!' to exclude).

rustic restore --glob '!**/*.log' latest /tmp/restore

rustic restore --dry-run <snapshot> <target> — Show what would be restored without writing files.

rustic restore --dry-run latest /tmp/restore

rustic restore --delete <snapshot> <target> — Delete files in the target that do not exist in the snapshot (mirror restore).

rustic restore --delete latest /var/www

rustic dump <snapshot>:<file> — Print the content of a single file from a snapshot to stdout.

rustic dump latest:/etc/nginx/nginx.conf

Mount Snapshots (FUSE)

rustic mount <mountpoint> — Mount all snapshots as a read-only virtual filesystem (requires FUSE).

rustic mount /mnt/rustic

rustic mount <snapshot-id> <mountpoint> — Mount a single snapshot as a read-only filesystem.

rustic mount latest /mnt/rustic

Forget & Prune (Retention)

rustic forget and rustic prune remove snapshots and unreferenced data permanently – always preview the effect first with --dry-run.

rustic forget --keep-last <n> — Keep only the n most recent snapshots and mark the rest for removal.

rustic forget --keep-last 7

rustic forget --keep-daily <n> --keep-weekly <n> --keep-monthly <n> — Apply a standard retention policy: keep n daily/weekly/monthly snapshots.

rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12

rustic forget --keep-within <duration> — Keep all snapshots created within the given duration (e.g., 7d, 4w, 6m, 1y).

rustic forget --keep-within 30d

rustic forget --keep-tag <tag> — Always keep snapshots that carry the given tag.

rustic forget --keep-tag important

rustic forget --filter-tag <tag> --keep-last <n> — Apply retention only to snapshots with a specific tag.

rustic forget --filter-tag daily --keep-last 7

rustic forget --dry-run --keep-daily <n> — Preview which snapshots would be removed without deleting them.

rustic forget --dry-run --keep-daily 7

rustic forget --keep-daily 7 --prune — Apply retention and immediately prune unreferenced data from the repository.

rustic forget --keep-daily 7 --prune

rustic prune — Remove data no longer referenced by any snapshot. Use --instant-delete to skip the safety delay.

rustic prune

Repository Maintenance

rustic check — Check the repository for errors and verify metadata integrity.

rustic check

rustic check --read-data — Verify all pack files by reading and decrypting their contents (slow, thorough).

rustic check --read-data

rustic check --read-data-subset <n>% — Verify a percentage of the data. Useful for staggered/scheduled verification.

rustic check --read-data-subset 10%

rustic repair index — Rebuild the repository index. Use if the index is lost or corrupted.

rustic repair index

rustic repair snapshots — Repair snapshots whose data is partially missing (creates fixed copies, originals stay).

rustic repair snapshots

rustic repoinfo — Show repository information: pack/blob counts, totals, compression ratio.

rustic repoinfo

rustic key list — List all encryption keys stored in the repository.

rustic key list

rustic key add — Add a new encryption password to the repository.

rustic key add

rustic copy --target <repo2> — Copy snapshots to a second repository (3-2-1 backup strategy).

rustic copy --target sftp:user@offsite.com:/backup

Tags & Snapshot Management

rustic tag <snapshot-id> --add <tag> — Add tags to existing snapshots without re-running backup.

rustic tag a1b2c3d4 --add archive

rustic tag <snapshot-id> --remove <tag> — Remove tags from existing snapshots.

rustic tag a1b2c3d4 --remove daily

rustic tag --set <tag> <snapshot-id> — Replace all tags of a snapshot with the given tag(s).

rustic tag --set archive a1b2c3d4

rustic merge <snapshot1> <snapshot2> — Merge two snapshots into a single new snapshot.

rustic merge a1b2c3d4 e5f6g7h8

Environment Variables

export RUSTIC_REPOSITORY=<path> — Set the default repository so -r can be omitted.

export RUSTIC_REPOSITORY=/mnt/backup/repo

export RUSTIC_PASSWORD=<password> — Set the repository password directly. Handy for unattended/cron backups, but RUSTIC_PASSWORD_FILE or RUSTIC_PASSWORD_COMMAND are safer.

export RUSTIC_PASSWORD=mysecretpassword

export RUSTIC_PASSWORD_FILE=<path> — Read the repository password from a file.

export RUSTIC_PASSWORD_FILE=/etc/rustic/password.txt

export RUSTIC_PASSWORD_COMMAND=<cmd> — Run a command and use its stdout as the password.

export RUSTIC_PASSWORD_COMMAND='pass show rustic/main'

export RUSTIC_USE_PROFILE=<profile> — Default profile to load if -P is not specified.

export RUSTIC_USE_PROFILE=daily

export RUSTIC_NO_PROGRESS=1 — Disable progress bars (useful in cron / non-TTY contexts).

export RUSTIC_NO_PROGRESS=1

Common Recipes

rustic -P daily backup && rustic -P daily forget --prune — Run a daily backup and apply retention from a profile in one cron line.

0 3 * * * rustic -P daily backup && rustic -P daily forget --prune

rustic snapshots --json | jq -r '.[-1][1][-1].id' — Get the ID of the latest snapshot as a plain string.

rustic snapshots --json | jq -r '.[-1][1][-1].id'

rustic backup --glob-file ~/.rusticignore --tag daily /home — Daily backup of /home with excludes and a tag for retention policies.

rustic backup --glob-file ~/.rusticignore --tag daily /home

rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune — Standard retention policy: 7 daily, 4 weekly, 12 monthly snapshots.

rustic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

rustic copy --target <repo2> && rustic -r <repo2> check — Sync to an offsite repo and verify it (3-2-1 strategy with integrity check).

rustic copy --target sftp:user@offsite:/backup && rustic -r sftp:user@offsite:/backup check

Conclusion

rustic pairs the speed and memory safety of Rust with restic's proven, deduplicated repository format – an appealing choice when you build on restic but want configuration profiles and more convenience. Treat your repository password like any other secret, and always preview forget/prune with --dry-run first. And a backup you have never restored is only a guess: test rustic restore regularly.