How to restore one file or folder from a restic snapshot

To restore one file or folder from restic, select an explicit snapshot ID, confirm the item’s original path inside that snapshot, and restore it into a new empty working directory. Inspect the recovered copy there before you replace anything used by a live service. This is safer than restoring directly into production and makes it possible to stop if you selected the wrong point in time.

A completed restore only proves that restic wrote data to the target. It does not prove that the snapshot contains the intended revision, that the restored file has the right permissions, or that the application will accept it. Treat selection, inspection, copy-back, and an application-level check as separate recovery steps.

• Use a specific snapshot ID rather than latest while investigating an incident.
• Restore to a scratch directory outside the live application tree.
• Keep the current live file until the recovered version has been checked and the service is working.

You need access to the same repository used for the backup, the repository password or recovery key, valid storage credentials, and a host with enough local disk space for the recovered item. Do not put passwords, cloud keys, or tokens directly in shell history, scripts, tickets, or command examples. Use your established secret-delivery mechanism and confirm that the restore host can reach the repository.

Write down the recovery question in operational terms: the hostname or source path, the item to recover, and the latest acceptable modification time. That prevents a common failure mode: restoring a technically valid but older revision because it happened to be the newest snapshot visible in a shared repository. If the requirement is based on data loss tolerance, set it from your [RPO and RTO plan](/blog/rpo-vs-rto-small-teams-backup-frequency), not from the convenience of the newest backup.

• Repository location and storage endpoint, if applicable.
• Repository password or recovery key held by an authorized operator.
• The original host name, backed-up source path, and approximate backup date.
• A separate, writable restore target with adequate capacity and restricted access.

Do not reach for latest until you know which backup set it means. A repository can contain snapshots from several hosts and several paths. The newest snapshot overall may belong to another server, may not include the path you need, or may have been created after the unwanted change.

List snapshots, narrow the result using the original host and backup path where available, then record the full snapshot ID you intend to use. An explicit recovery point makes the work repeatable and prevents the meaning of latest from changing while you investigate.

The following commands are illustrative. Run them from a controlled administrative shell, adapt the placeholders, and test the workflow outside production before relying on it during an outage. They assume your normal environment already supplies repository and credential settings without exposing secrets in the command line.

• Prerequisites: the restic CLI is installed; repository and credentials are available through approved environment variables, files, or credential tooling; and the account can read the repository.
• Safe context: read-only repository inspection from an administrator workstation or a recovery host. Do not run destructive retention or prune commands during a restore investigation.

This example filters the snapshot list by the original machine and backup root. Replace the placeholders with values from your backup inventory. If your repository contains only one source, you may not need both filters, but using them is a useful guard against choosing another host’s snapshot.

Expected result: restic displays matching snapshot IDs, timestamps, host names, tags, and paths. Select the ID whose timestamp is appropriate for the incident, then use ls to inspect the snapshot’s own tree. The paths shown by ls are the paths you must use in a selective restore.

• Failure signal: no matching snapshot usually means the host name or source path differs from your assumption, the repository is not the expected one, or that scope was never backed up. Broaden the listing deliberately; do not guess an ID.
• Failure signal: an authentication, repository, or storage error is a recovery-plan issue. Preserve the exact error, confirm endpoint, prefix, credentials, and repository password, and avoid creating a new repository in the same location by mistake.

Create an empty target that is not under the application’s live data directory. Restic recreates the backed-up hierarchy beneath --target; a file stored as /srv/app/uploads/report.pdf will normally appear below $RESTORE_TARGET/srv/app/uploads/report.pdf. This behavior is useful because it keeps the recovered data separate from the live path.

First run a dry run when you are uncertain about an include pattern or scope. Then run the actual restore with the same snapshot ID and include path. Use a directory path to restore a folder and its contents. Do not add --delete for a one-item recovery: it is intended for controlled reconciliation and can remove target files absent from the selected snapshot.

Expected result: restic exits successfully and reports restore progress or completion. A successful exit is evidence that the selected data was restored to the scratch target; it is not yet evidence that the item is the correct business version or that it can safely replace the live copy.

• Production caveat: ensure the scratch target is private. A recovered configuration file, export, upload, or key material may contain sensitive data.
• Production caveat: do not restore directly over files a running application can modify. Quiesce the service only after you have inspected the scratch copy and have an approved replacement plan.

Start with ordinary filesystem checks: confirm the recovered path exists, inspect its type, size, ownership, mode, and modification time, and compare it with the incident requirement. For a document, image, or export, open it with the software that normally reads it. For a configuration file, review a diff against the current version and validate its syntax with the relevant application tool where possible.

Checksums are useful only when you have a trusted reference hash for the version you expect. They establish byte equality with that reference, not whether the selected historic version is operationally correct. For a folder, examine the expected file count and critical child paths; do not infer completeness merely from the top-level directory existing.

If the recovered item is database-related, do not treat a copied database data directory as an interchangeable backup artifact. Use the database engine’s supported logical or physical recovery procedure and validate it in an isolated instance. See the [PostgreSQL backup and restore documentation](https://www.postgresql.org/docs/current/backup.html) for PostgreSQL-specific recovery methods.

• Compare: intended timestamp, path, content, permissions, owner, and group.
• Validate: use an application read, parser, syntax check, or isolated smoke test suited to the file type.
• Record: snapshot ID, restore target, validation result, and the operator who approved copy-back.