restic — Fast, Encrypted Backups

restic is a modern backup program that stores your data in encrypted repositories and deduplicates automatically – every data chunk is saved only once, no matter how many snapshots or hosts it appears in. You back up locally, over SFTP, or to cloud storage such as S3 and Backblaze B2, and plaintext never leaves your machine. This guide takes you from initializing a repository through backups, snapshots and restores to retention policies and maintenance.

Repository Initialization

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

restic init --repo /mnt/backup/myrepo

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

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

restic -r s3:s3.amazonaws.com/<bucket> init — Initialize a repository in an S3-compatible bucket. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

restic -r s3:s3.amazonaws.com/my-backup-bucket init

restic -r b2:<bucket>:<path> init — Initialize a repository in Backblaze B2. Set B2_ACCOUNT_ID and B2_ACCOUNT_KEY.

restic -r b2:my-bucket:restic-repo init

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

restic -r rclone:gdrive:backups/restic init

Creating Backups

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

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

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

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

restic -r <repo> backup --tag <tag> <path> — Add one or more tags to the snapshot for easy filtering.

restic -r /mnt/backup/repo backup --tag daily --tag web /var/www

restic -r <repo> backup --exclude <pattern> <path> — Exclude files or directories matching the pattern.

restic -r /mnt/backup/repo backup --exclude 'node_modules' /home/user/projects

restic -r <repo> backup --exclude-file <file> <path> — Read exclude patterns from a file (one pattern per line).

restic -r /mnt/backup/repo backup --exclude-file ~/.resticignore /home/user

restic -r <repo> backup --files-from <listfile> — Read files and directories to back up from a file.

restic -r /mnt/backup/repo backup --files-from /etc/restic/includes.txt

restic -r <repo> backup --verbose <path> — Show detailed output including each file being backed up.

restic -r /mnt/backup/repo backup --verbose /home/user

Listing Snapshots

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

restic -r /mnt/backup/repo snapshots

restic -r <repo> snapshots --tag <tag> — List snapshots filtered by tag.

restic -r /mnt/backup/repo snapshots --tag daily

restic -r <repo> snapshots --host <hostname> — List snapshots from a specific host.

restic -r /mnt/backup/repo snapshots --host webserver01

restic -r <repo> snapshots --json — Output snapshot list as JSON for scripting.

restic -r /mnt/backup/repo snapshots --json | jq '.[].id'

restic -r <repo> ls <snapshot-id> — List files inside a specific snapshot.

restic -r /mnt/backup/repo ls a1b2c3d4

restic -r <repo> ls latest — List files inside the most recent snapshot.

restic -r /mnt/backup/repo ls latest

Restoring Data

restic -r <repo> restore <snapshot-id> --target <path> — Restore a full snapshot to the given target directory.

restic -r /mnt/backup/repo restore a1b2c3d4 --target /tmp/restore

restic -r <repo> restore latest --target <path> — Restore the latest snapshot.

restic -r /mnt/backup/repo restore latest --target /tmp/restore

restic -r <repo> restore latest --target <path> --include <pattern> — Restore only files matching a pattern from the latest snapshot.

restic -r /mnt/backup/repo restore latest --target /tmp/restore --include '/home/user/Documents'

restic -r <repo> restore latest --target <path> --exclude <pattern> — Restore all files except those matching the pattern.

restic -r /mnt/backup/repo restore latest --target /tmp/restore --exclude '*.log'

restic -r <repo> dump <snapshot-id> <file> — Print the content of a single file from a snapshot to stdout.

restic -r /mnt/backup/repo dump latest /etc/nginx/nginx.conf

Mount Snapshots (FUSE)

restic -r <repo> mount <mountpoint> — Mount all snapshots as a virtual filesystem (requires FUSE). Browse with a file manager.

restic -r /mnt/backup/repo mount /mnt/restic

restic -r <repo> mount --snapshot-template <tpl> <mountpoint> — Customize the directory name format for each snapshot.

restic -r /mnt/backup/repo mount --snapshot-template '2006-01-02_15-04-05' /mnt/restic

Forget & Prune (Retention Policies)

restic -r <repo> forget --keep-last <n> — Keep only the n most recent snapshots.

restic -r /mnt/backup/repo forget --keep-last 7

restic -r <repo> forget --keep-daily <n> --keep-weekly <n> --keep-monthly <n> — Apply a standard retention policy: keep n daily, weekly, and monthly snapshots.

restic -r /mnt/backup/repo forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12

restic -r <repo> forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune — Apply retention policy and immediately prune unreferenced data. Destructive: deletes data permanently – preview with --dry-run first.

restic -r /mnt/backup/repo forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic -r <repo> forget --dry-run --keep-daily 7 — Preview which snapshots would be removed without actually deleting them.

restic -r /mnt/backup/repo forget --dry-run --keep-daily 7

restic -r <repo> forget --tag <tag> --keep-last 3 — Apply retention policy only to snapshots with a specific tag.

restic -r /mnt/backup/repo forget --tag daily --keep-last 3

restic -r <repo> prune — Remove data from the repository that is no longer referenced by any snapshot. Destructive: permanently frees occupied storage and cannot be undone.

restic -r /mnt/backup/repo prune

Repository Maintenance

restic -r <repo> check — Check the repository for errors and verify data integrity.

restic -r /mnt/backup/repo check

restic -r <repo> check --read-data — Verify all data by reading and decrypting every pack file (slow but thorough).

restic -r /mnt/backup/repo check --read-data

restic -r <repo> check --read-data-subset=<n>/<total> — Read only a fraction of the data during check. Useful for staggered verification.

restic -r /mnt/backup/repo check --read-data-subset=1/10

restic -r <repo> stats — Show statistics about the repository (total size, deduplicated size, snapshot count).

restic -r /mnt/backup/repo stats

restic -r <repo> stats --mode raw-data — Show disk size of all data stored in the repository.

restic -r /mnt/backup/repo stats --mode raw-data

restic -r <repo> key list — List all encryption keys stored in the repository.

restic -r /mnt/backup/repo key list

restic -r <repo> key add — Add a new encryption password to the repository.

restic -r /mnt/backup/repo key add

restic -r <repo> rebuild-index — Rebuild the repository index. Use if the index is lost or corrupted.

restic -r /mnt/backup/repo rebuild-index

restic -r <repo> copy --repo2 <repo2> — Copy all snapshots from repo to a second repository (3-2-1 backup strategy).

restic -r /mnt/local/repo copy --repo2 sftp:user@offsite.com:/backup

Environment Variables

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

export RESTIC_REPOSITORY=/mnt/backup/repo

export RESTIC_PASSWORD=<password> — Set the repository password. Useful for unattended/cron backups, but it then sits in the environment in plaintext – prefer RESTIC_PASSWORD_FILE or RESTIC_PASSWORD_COMMAND.

export RESTIC_PASSWORD=mysecretpassword

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

export RESTIC_PASSWORD_FILE=/etc/restic/password.txt

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

export RESTIC_PASSWORD_COMMAND='pass show restic/main'

Authentication for S3-compatible backends.

export AWS_ACCESS_KEY_ID=<key>
export AWS_SECRET_ACCESS_KEY=<secret>

Authentication for Backblaze B2 backend.

export B2_ACCOUNT_ID=<id>
export B2_ACCOUNT_KEY=<key>

Common Recipes

restic -r <repo> backup --exclude-file ~/.resticignore --tag daily /home — Daily backup of /home with excludes and a tag for retention policies.

restic -r /mnt/backup/repo backup --exclude-file ~/.resticignore --tag daily /home

restic -r <repo> forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune — Standard retention policy: 7 daily, 4 weekly, 12 monthly snapshots.

restic -r /mnt/backup/repo forget --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --prune

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

restic -r /mnt/backup/repo snapshots --json | jq '.[-1].id' -r

restic -r <repo> backup <path> && restic -r <repo> forget --keep-daily 7 --prune — Backup and clean up old snapshots in one cron job command.

restic -r /mnt/backup/repo backup /home && restic -r /mnt/backup/repo forget --keep-daily 7 --prune

Conclusion

restic takes the hard parts of a backup system off your hands: encryption, deduplication and snapshot management run transparently in the background, while the same commands work for local disks, SFTP and cloud storage. Treat the repository password like a master key – without it your backups are irrecoverably lost, so keep RESTIC_PASSWORD out of plaintext and reach for RESTIC_PASSWORD_FILE or RESTIC_PASSWORD_COMMAND in any serious setup. Use forget --prune and prune deliberately and preview them with --dry-run, because they delete data permanently.