How to Set Up Borg Prune and Compact Without Long Backup Gaps

To avoid long Borg backup gaps, run retention pruning after a successful backup but schedule repository compaction less often and outside the main backup window. Borg 1.4 separates archive deletion from physical space reclamation, so there is no requirement to run borg compact after every borg prune.

This guide targets the current Borg 1.4.x stable command model. Borg 2 changes repository and archive semantics in several areas, so check the installed version before copying automation from another major release.

Confirm the Borg Version and Repository

borg --version
borg info /mnt/backup/borg-repo
borg list /mnt/backup/borg-repo

The Borg FAQ notes that Borg uses a repository-wide lock and only one process can have write access at a time. If a long compact overlaps the next scheduled backup, the backup waits for the lock or fails when its lock timeout expires.

Define Retention With a Dry Run First

borg prune is destructive to archive history. Borg's prune documentation strongly recommends testing with --dry-run and --list.

borg prune   --dry-run   --list   --keep-daily 7   --keep-weekly 4   --keep-monthly 6   --glob-archives '{hostname}-*'   /mnt/backup/borg-repo

If one repository contains backups from multiple machines or datasets, the archive filter is essential. Without a restrictive filter, Borg 1.4 considers all archives in the repository as candidates for the same retention rules.

Run Prune Only After a Successful Backup

#!/bin/sh
set -eu
REPO=/mnt/backup/borg-repo
ARCHIVE='{hostname}-{now:%Y-%m-%d_%H-%M}'

borg create --stats "$REPO::$ARCHIVE" /srv/data

borg prune   --list   --keep-daily 7   --keep-weekly 4   --keep-monthly 6   --glob-archives '{hostname}-*'   "$REPO"

Do not prune because a scheduler fired; prune because a new backup completed successfully and the retention policy has already been validated.

-15% OFF

ZimaBoard 2 - Mini Home Server for Your Big Idea

Single board computer zimaboard2

$339.00 - $519.00

Buy Now

Understand Why Prune Does Not Immediately Free Space

Since Borg 1.2, compaction is separated from normal repository-writing commands. Borg's separate compaction notes explain that deleting or pruning archives does not immediately reclaim all repository disk space.

borg create
    |
new archive committed
    |
borg prune
    |
old archives removed from retention set
    |
borg compact
    |
unused segment space reclaimed

This is useful for scheduling because daily backups do not need to pay the full cost of rewriting partially used repository segments.

Schedule Compact Less Often Than Prune

• backup: every night;
• prune: after each successful backup or a few times per week;
• compact: once per week during a quiet period;
• full repository check: on a separate, less frequent schedule.

# Daily backup + prune
0 1 * * * /usr/local/sbin/borg-backup

# Weekly compact
0 4 * * 0 /usr/local/sbin/borg-compact

If backups often run for several hours, move compaction farther away or use a timer with explicit dependencies.

Use the Default Compact Threshold Before Forcing Maximum Rewrites

The current compact documentation uses a 10% threshold by default.

borg compact --progress /mnt/backup/borg-repo

That default is a good starting point when your priority is a short maintenance window. Avoid automatically using --threshold 0; it rewrites whenever any space can be saved and can be significantly slower on a large repository.

Prevent Maintenance From Colliding With the Next Backup

If a job may legitimately wait for another Borg process, set a bounded lock wait:

borg --lock-wait 1800 create   /mnt/backup/borg-repo::'{hostname}-{now}'   /srv/data

Do not use a very long lock wait as a substitute for good scheduling. Monitor when the backup actually starts and finishes.

If several clients share one repository, stagger their schedules. Borg's FAQ notes that multiple repositories can reduce lock contention when cross-client deduplication is not important.

Use Quick Stats When Reporting Is Slowing Prune

Borg 1.4.5 added --quick-stats to create, delete, and prune, avoiding slower repository-wide statistics when they are not needed.

borg prune   --quick-stats   --keep-daily 7   --keep-weekly 4   --keep-monthly 6   --glob-archives '{hostname}-*'   /mnt/backup/borg-repo

Keep Free Space Available Before You Need Compact

Do not wait until the repository filesystem reaches zero free space. Borg cannot reliably perform normal repository-writing work on a completely full filesystem.

df -h /mnt/backup
borg info /mnt/backup/borg-repo

For a broader NAS backup plan, the ZimaOS 3-2-1 backup guide is a useful reminder that repository retention is only one layer of backup design.

Validate the Schedule Before Trusting It

• Did every backup create a new archive?
• Did prune run only after successful backups?
• Did the retention set match the dry-run plan?
• Did weekly compact finish before the next backup?
• Did free space increase after compact?
• Did any job spend unexpected time waiting for the Borg lock?

If compact repeatedly overlaps the next backup, reduce compaction frequency, keep the default threshold, move compact to a quieter window, or split unrelated workloads into separate repositories.

A Low-Gap Borg Maintenance Pattern

DAILY
01:00  borg create
        |
        +-- success --> borg prune
        |
        +-- failure --> keep old archives, alert

WEEKLY
04:00  borg compact

PERIODIC
        borg check
        restore-test selected files

The central rule is simple: prune protects retention policy; compact reclaims storage; they do not need to run at the same frequency.