Learn Borg Backup - Borg 1.4.5 vs Borg 2.0
Two Borg lines coexist: the stable 1.4.x for production and 2.0, which is being overhauled. This episode compares the two — release status, the repository format overhaul, hash index, the --match-archives option, and segment management — and gives you guidance on when to move to 2.0 without putting production at risk.
#Introduction
Throughout this series we have worked with Borg 1.4.5. But in episode 1 we mentioned that Borg 2.0 is in development — and now it is time to dissect the differences. Understanding the release map is not just about the prestige of "using the newest version"; it is about deciding when a migration delivers real value and when it only adds risk.
#Borg 1.4.5: The Production Choice
#Status
Borg 1.4.5 (released 1 July 2026) is the peak of the 1.4.x branch, stable throughout 2025-2026. It carries security fixes (the two CVEs in episode 15), full compatibility with every feature we used in this series — append-only, compact, check, FUSE mount — and a mature borgmatic ecosystem.
#Why It Remains the Production Choice
- Maturity: the repository format is stable and widely understood.
- Ecosystem: borgmatic, borgweb, and other tooling are tested against 1.4.x.
- Compatibility: 1.4.x repos are readable by the entire existing toolchain.
- Long-term support: fixes for this branch are still being released.
#Borg 2.0: The Big Overhaul (Still Beta)
#Beta Status
Borg 2.0 is still in beta (2.0.0b10) — do not use it for production. Its goal is not small fixes but an overhaul of the repository format that brings several fundamental changes.
#Main Changes
A new repository format with a better hash index. The 2.0 repository introduces a structure that scales better and is more efficient for very large repositories — the chunk catalog is optimized so operations do not degrade with hundreds of thousands of archives.
The --match-archives option. Archive filtering becomes more expressive. In 1.4, archive selection uses the limited --prefix and --glob-archives. In 2.0, --match-archives accepts far more flexible patterns:
borg prune --match-archives 'sh:{hostname}-*' \
--keep-daily 7 --keep-weekly 4Overhauled segment management. How data segments are managed and compacted is changed to reduce overhead and improve reliability on large repositories.
A changed CLI structure. Commands that were flat (e.g. borg create, borg check) are split into nested subcommands like borg repo-create, borg archive create, borg repo-check, and borg archive-check. This is cleaner, but it means old scripts need adaptation when migrating.
#A Brief Comparison
+------------------------+---------------------+--------------------------+
| Aspect | Borg 1.4.5 | Borg 2.0 (beta) |
+------------------------+---------------------+--------------------------+
| Status | stable, production | beta (2.0.0b10) |
| Repository format | 1.x | new (v2) |
| Hash index | good | more scalable |
| Archive matching | prefix/glob | --match-archives |
| Segment management | mature | overhauled |
| CLI | flat | nested |
+------------------------+---------------------+--------------------------+Warning
Borg 2.0 repositories are not compatible with 1.4.x. Trying to read a 2.0 repo with borg 1.4 will fail — and vice versa. Never "experiment" with a production repo using a 2.0 beta binary.
#When to Move to Borg 2.0
#Wait for These Signals
- An official stable 2.0 release is announced (not beta).
- The changelog shows features you need — e.g.
--match-archivesor repository scale that starts hitting limits in 1.4.x. - The ecosystem is ready: borgmatic and supporting tooling already support 2.0.
#A Safe Migration Path
A 1.4 → 2.0 migration is not an in-place upgrade, because the formats differ. The safe pattern:
- Create a new repository with Borg 2.0 in a staging environment.
- Re-back up data from the staging host.
- Test a full restore from the 2.0 repo.
- If it passes, do a per-host cutover — do not migrate everything at once.
Tip
As an SRE, you are never required to be the earliest adopter. A healthy rule: production follows stable, experiments follow beta. Install Borg 2.0 in a trial VM, learn the differences, and let its maturity work for you — not the other way around, with you bearing the beta risk.
#Common Pitfalls
- Production on beta: a 2.0-beta repo risks its format changing again before stable — production backups in a format that is not final.
- In-place migration: forcing a 1.4 repo to be read by 2.0 (or vice versa) causes read failures. Build a new repo.
- Reusing old scripts directly: the CLI structure changed; audit all backup scripts before the cutover.
- Ignoring the ecosystem: borgmatic that does not support 2.0 yet means losing automation — a value greater than the borg version alone.
#Closing
- Borg 1.4.5 is the stable, mature production choice.
- Borg 2.0 (beta) overhauls the repo format: a better hash index,
--match-archives, segment management, and a nested CLI. - The 2.0 repository format is not compatible with 1.x.
- Migration = new repo + restore tests, not an in-place upgrade.
- Production follows stable; experiments follow beta.
In episode 18 we push the performance limits: performance & large datasets — tuning chunker parameters, compression levels, and caching, benchmarking dedup and speed, TB-level backup cases, and throttling with ionice/nice.