简体中文
EnglishWhat are restic's compatibility guarantees?
Updated
restic follows Semantic Versioning, and the repository plus the data structures stored inside it are treated as the "Public API" for that purpose. In practice: once version 1.0.0 is released, all repositories within one major version are guaranteed to be backward compatible — as long as the major version is not incremented, saved data can be read and restored. Before 1.0.0, maintainers and developers do their utmost to keep backward compatibility and stability, but breaking changes are possible without a major version bump.
The core guarantee
The reason restic commits to this is stated directly on the site: backward compatibility for backups matters so that users are always able to restore saved data. A backup tool that can't restore older repositories is not much of a backup tool, so compatibility is framed as a promise about restorability, not just about the software running.
The mechanism is versioning the data, not the binary:
| Element | Role under Semantic Versioning |
|---|---|
| Repository format | Part of the "Public API" |
| Data structures inside the repository | Part of the "Public API" |
| Major version number | Boundary of the backward-compatibility guarantee |
| Minor/patch versions | Should not break reading or restoring existing repositories |
What this means at each stage
After 1.0.0
- All repositories within one major version are backward compatible.
- As long as the major version is not incremented, data can be read and restored.
- A major version increment is the signal that compatibility may break.
Before 1.0.0 (initial development)
- Maintainers and developers "will do their utmost" to keep backward compatibility and stability.
- Breaking changes are still possible without increasing the major version.
- The site also states the project strives to be fully backward compatible to all prior versions.
So the pre-1.0.0 period is best-effort, while the post-1.0.0 period is a guarantee. If you are planning long-term archival storage, that distinction is the one to weigh.
How to apply this when choosing a version
- Long-lived archives: prefer a release line at or beyond 1.0.0, where the same-major-version guarantee applies, and avoid jumping major versions without checking.
- Testing or short-term use: pre-1.0.0 builds are usable, but treat the possibility of a breaking change as real and keep independent copies of anything critical.
- Upgrading: staying within the same major version is the safe path by design; a major version change is the point at which you should verify restorability rather than assume it.
- Verification: restic's own description emphasizes being "verifiably" able to restore, so the compatibility promise is meant to be checked by actually restoring, not just trusted.
Where to confirm details
The compatibility statement lives on the restic homepage, with installation and usage details in the manual (released version and latest development version), and the design document describing the on-disk data structures. For questions about a specific version or repository, the project points users to its forum for usage and support questions and to GitHub issues for bugs or feature suggestions.