How does --older work with borg prune?

[tve]

I'm not understanding the effect of the --older option in borg prune. It seems to have no effect?

For example:

# borg prune --dry-run -v --list --older 20d -d 2
Repository contains 5 archives.
Applying rules to the matching 5 archives...
Keeping 2 archives, pruning 3 archives.
Keeping archive (rule: daily #1):            rack2         daily-full 2026-08-29 23:54:01 -0400 RC=0,V
Keeping archive (rule: daily #2):            rack2         daily-full 2026-08-28 23:54:02 -0400 RC=0
Would prune:                                 rack2         daily-full 2026-08-27 23:54:01 -0400 RC=0
Would prune:                                 rack2         daily-full 2026-08-26 23:54:01 -0400 RC=0
Would prune:                                 rack2         daily-full 2026-08-26 23:54:01 -0400 RC=0
# date
Mon Aug 31 06:11:23 PM EDT 2026

I expected borg not to prune any archive because I asked it to only consider ones that are older than 20 days.

Overall the --older is a bit ambiguous. For example, if I specify --older 2d -d 5 does that mean "ignore archives newer than 2 days and then keep 5 daily archives before that" or does it mean "keep the last 5 daily archives and ignore any additional archives in the past two days"?

I probably have it all wrong 😆

[bogdanr]

--older is parsed but never used by prune. In 2.0.0b23 do_prune builds its archive list from args.name / args.match_archives only, and nothing anywhere reads args.older or args.newer. The shared archive-filter group defines those flags for every command that uses it, so you get no error and no effect. Master has since passed older_newer=False for prune, so it will reject the flag rather than silently ignore it.

The option you want is --from:

borg prune --dry-run -v --list --from "$(date -d '20 days ago' -Is)" -d 2

Note it takes an ISO timestamp or a path it stats, not an interval like 20d.

On your second question, --from behaves like your first reading. Archives at or after the timestamp are kept outright under the from rule and then dropped from the candidate list, so the retention rules only ever see older archives. --from two days ago with -d 5 keeps everything from the last two days, plus 5 daily archives before that.

[tve]

Thanks for all the info, very appreciated! I think I skipped over --from 'cause I didn't want to figure out how to do the timestamp arithmetic 😄 ...

Note that --older is mentioned in the docs under the common options in https://borgbackup.readthedocs.io/en/2.0.0b23/usage/prune.html so there's apparently a doc inconsistency.

[ThomasWaldmann]

These options will be removed from prune in next beta, it is already fixed in master branch.

[tve]

It would be great to copy the $(date ...) incantation into the examples...

[PhrozenByte]

--from $(date …) is already covered in the docs.

Note that --from primarily affects the retention calculations for interval-based pruning; the fact that it also skips archives is merely a side effect. Since you're using count-based pruning (-d 2) in your example, it has no effect here. However, if you ever switch to interval-based pruning (-d 2d), it will have a major impact. If you simply want to keep everything from the last 20 days without affecting other --keep options, use --keep 20d (formerly known as --keep-within) instead.

--from is intended to make interval-based pruning less exact and better align it with your backup strategy. For example, if you create daily backups, run with --from "$(date +%F)"; for weekly backups, run with --from "$(date -d 'monday this week' +%F)"; and for monthly backups, run with --from "$(date +%Y-%m)".