borg-compact(1)

🌸 borg-compact 💅

okay bestie, say hi to borg-compact, a page from the borg backup tool manual. she's the one who takes out the trash 🗑️✨

---

✨ NAME ✨

borg-compact — Collects garbage in the repository. literally her whole job, no cap 🧹

---

🎀 SYNOPSIS 🎀

borg [common options] compact [options]

---

💖 DESCRIPTION 💖

Free repository space by deleting unused chunks. that's it, that's the vibe 🦋

borg compact analyzes all existing archives to determine which repository objects are actually used (referenced). then — and this is the moment — it deletes all unused objects from the repository to free space. main character behaviour fr fr 👑

so like… where do these unused objects even come from?? 🤔

Unused objects may result from:

• use of borg delete or borg prune
• interrupted backups (consider retrying the backup before running compact) 😭
• backups of source files that encountered an I/O error mid-transfer and were skipped 🙈
• corruption of the repository (e.g., the archives directory lost entries; see notes below) 💀

borg compact reclaims objects the chunk index knows about, plus redundant copies of indexed chunks (e.g. written by concurrent backups) that it finds while rewriting a pack. Other bytes no index entry covers, such as packs left behind by a backup that crashed before recording its objects, are re-indexed by borg check --repair and reclaimed by the next borg compact. ✨

borg compact does not rewrite or merge packs that borg check recorded as corrupt and warns about them. borg check --repair --verify-data deletes the corrupt chunks by rewriting their packs. It does not remove damage outside any chunk (e.g. bytes appended to a pack): a pack with such damage and no corrupt chunk stays recorded corrupt and borg compact warns about it on every run, a pack that also has a corrupt chunk is rewritten with that damage copied into the new pack (refs #10026). 🫶

You usually do not want to run borg compact after every write operation, but either regularly (e.g., once a month, possibly together with borg check) or when disk space needs to be freed. lowkey just do it on a schedule 💅

the cost of compacting (a lil gatekeeping, respectfully) 🚪

Compacting anything rewrites the whole chunk index and invalidates every client's cached copy of it, so borg compact only acts when the gain is worth that cost:

• All-packs gate: it drops or rewrites packs only when the space they would free reaches --threshold divided by 5 percent (2% at the default threshold) of the total pack size. Below that floor it leaves the repository (and the chunk index) untouched. Use --threshold 0 to disable the gate and always compact. periodt.
• Tiny-pack merging: incremental backups tend to leave one small, fully-used pack per run. borg compact combines such tiny packs into larger ones, but only once their combined size is large enough to fill at least one full-size pack, so a merge always produces a pack that will not be a merge candidate again. queen of efficiency 👑

⚠️ Important: ⚠️

After compacting, it is no longer possible to use borg undelete to recover previously soft-deleted archives. so like… be sure, bestie 😭

borg compact might also delete data from archives that were "lost" due to archives directory corruption. Such archives could potentially be restored with borg check --find-lost-archives [--repair], which is slow. You therefore might not want to do that unless there are signs of lost archives (e.g., when seeing fatal errors when creating backups or when archives are missing in borg repo-list). ngl, only go looking if something's actually sus 👀

With --stats, borg additionally reports the on-disk size of the pack files before and after compaction (the reported compression factor is based on that size). cute numbers, love that for us 📊

---

⭐ OPTIONS ⭐

See borg-common(1) for common options of Borg commands. yes bestie, go read that one too, iykyk 🫶

🌈 options 🌈

• -n, --dry-run — do not change the repository, just show what compact would free. window shopping, no spending 💸
• -s, --stats — print repository size statistics 📈
• --threshold PERCENT — rewrite a pack when at least PERCENT of its bytes are unused; also gates whether to compact at all (see the all-packs gate above), 0 disables that gate (default: 10) 🎚️

---

🦋 EXAMPLES 🦋

# Free repository disk space by deleting unused chunks (rewriting packs as needed)
$ borg compact

look at her go ✨

---

👑 SEE ALSO 👑

borg-common(1)

---

💜 Author 💜

The Borg Collective 🌈 (a whole collective, very slay of them)

---

okay that's the whole page bestie, mwah 💋 this was borg-compact(1), from the borg backup tool, dated 2026-10-07 — go free up that disk space, you got this 🫶✨🎀