.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-compact" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-compact \- Collects garbage in the repository.
.SH SYNOPSIS
.sp
borg [common options] compact [options]
.SH DESCRIPTION
.sp
Free repository space by deleting unused chunks.
.sp
\fBborg compact\fP analyzes all existing archives to determine which repository
objects are actually used (referenced). It then deletes all unused objects
from the repository to free space.
.sp
Unused objects may result from:
.INDENT 0.0
.IP \(bu 2
use of \fBborg delete\fP or \fBborg prune\fP
.IP \(bu 2
interrupted backups (consider retrying the backup before running compact)
.IP \(bu 2
backups of source files that encountered an I/O error mid\-transfer and were skipped
.IP \(bu 2
corruption of the repository (e.g., the archives directory lost entries; see notes below)
.UNINDENT
.sp
\fBborg compact\fP 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 \fBborg check \-\-repair\fP and reclaimed by
the next \fBborg compact\fP\&.
.sp
You usually do not want to run \fBborg compact\fP after every write operation, but
either regularly (e.g., once a month, possibly together with \fBborg check\fP) or
when disk space needs to be freed.
.sp
Compacting anything rewrites the whole chunk index and invalidates every client\(aqs
cached copy of it, so \fBborg compact\fP only acts when the gain is worth that cost:
.INDENT 0.0
.IP \(bu 2
All\-packs gate: it drops or rewrites packs only when the space they would free
reaches \fB\-\-threshold\fP 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 \fB\-\-threshold 0\fP to disable the gate and always compact.
.IP \(bu 2
Tiny\-pack merging: incremental backups tend to leave one small, fully\-used pack per
run. \fBborg compact\fP 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.
.UNINDENT
.sp
\fBImportant:\fP
.sp
After compacting, it is no longer possible to use \fBborg undelete\fP to recover
previously soft\-deleted archives.
.sp
\fBborg compact\fP might also delete data from archives that were \(dqlost\(dq due to
archives directory corruption. Such archives could potentially be restored with
\fBborg check \-\-find\-lost\-archives [\-\-repair]\fP, 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
\fBborg repo\-list\fP).
.sp
With \fB\-\-stats\fP, borg additionally reports the on\-disk size of the pack files
before and after compaction (the reported compression factor is based on that size).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS options
.INDENT 0.0
.TP
.B  \-n\fP,\fB  \-\-dry\-run
do not change the repository, just show what compact would free
.TP
.B  \-s\fP,\fB  \-\-stats
print repository size statistics
.TP
.BI \-\-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)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Free repository disk space by deleting unused chunks (rewriting packs as needed)
$ borg compact
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH Author
The Borg Collective
.\" End of generated man page.