You Set Retention to 7 Days and the Disk Is Still 91% Full
You told Proxmox Backup Server (PBS) to keep seven daily backups. You deleted a pile of old snapshots by hand. You checked the datastore usage graph and it did not move. It is 2 AM, the disk is nearly full, and you start to suspect the software is lying to you.
It is not lying. Pruning and freeing space are two different jobs in PBS, and the second one runs on its own schedule with a built-in delay. Once you understand how PBS stores data, the behavior makes sense, and three maintenance jobs (prune, garbage collection, verify) keep a datastore healthy with little attention beyond reading the task logs.
This post covers how chunk-level dedup works, what each job does, the CLI commands to set them up, and a worked retention example you can check against the prune simulator. Everything here was checked against the PBS 4.2 documentation (the docs build is 4.2.12-1).
How PBS Stores Your Data: Chunks, Not Files
PBS does not write a backup as one big file. The client splits the data into chunks. Each chunk is identified by the SHA-256 checksum of its content, and it lands in the datastore’s .chunks/ directory, grouped into subdirectories by the first two bytes of the checksum (four hex digits, 0000 to ffff).
Each snapshot is a manifest plus small index files that list which chunks make up the backup. Two snapshots that share data point at the same chunk files. That is the whole dedup mechanism: same content, same checksum, one copy on disk.
There are two chunking modes:
- Fixed-size chunks for block-based backups, such as VM disk images. The image is cut into equal pieces (typically 4 MiB). On Proxmox VE, dirty bitmaps track which blocks changed, so only modified chunks get uploaded.
- Dynamically sized chunks for file-based backups. A rolling hash (a Buzhash variant) over the archive picks chunk boundaries from the content. If a file grows by a few bytes, the boundaries downstream re-sync and most chunks stay identical.
Every snapshot references all of its chunks, so each one restores as a full backup. There is no “restore the full, then replay five incrementals” chain to break. That is nice. It also has a consequence for deleting: a chunk may belong to a dozen snapshots, so PBS cannot just delete chunks when you delete a snapshot.
One more detail matters if you use client-side encryption. For encrypted chunks, the checksum is computed over the plain content plus the key. The same data encrypted with two different keys does not dedup against itself.
Job One: Prune Decides What Is Not Needed
Prune applies your retention rules to snapshots. When a snapshot is pruned, PBS removes only its metadata: the manifest, indices, blobs, log, and notes. The chunks stay exactly where they were.
The retention options are:
| Option | Keeps |
|---|---|
keep-last | the newest N snapshots |
keep-hourly | the latest snapshot of each of the last N hours |
keep-daily | the latest snapshot of each of the last N days |
keep-weekly | the latest snapshot of each of the last N weeks (ISO weeks, Monday to Sunday) |
keep-monthly | the latest snapshot of each of the last N months |
keep-yearly | the latest snapshot of each of the last N years |
Two rules from the docs trip people up. First, periods without backups do not count. If you skip a week, keep-weekly 4 reaches one week further back instead of leaving a hole. Second, the options run in the order above, and each one skips periods that an earlier option already covered. Those periods do not count toward its N. Snapshots with timestamps in the future are always kept.
Prune also deletes old unfinished or incomplete backups, unless the failed one is newer than the last successful backup. In that case PBS keeps the latest failure so you can look at it.
A worked example
Say you run one nightly backup of a group, and today is 2026-11-19. You have 100 days of history and these settings:
keep-last: 3keep-daily: 7keep-weekly: 4keep-monthly: 3Here is what survives (the newest snapshot is last night’s, 2026-11-18):
| Snapshot | Day | Kept by |
|---|---|---|
| 2026-11-18 | Wed | keep-last |
| 2026-11-17 | Tue | keep-last |
| 2026-11-16 | Mon | keep-last |
| 2026-11-15 | Sun | keep-daily |
| 2026-11-14 | Sat | keep-daily |
| 2026-11-13 | Fri | keep-daily |
| 2026-11-12 | Thu | keep-daily |
| 2026-11-11 | Wed | keep-daily |
| 2026-11-10 | Tue | keep-daily |
| 2026-11-09 | Mon | keep-daily |
| 2026-11-08 | Sun | keep-weekly |
| 2026-11-01 | Sun | keep-weekly |
| 2026-10-25 | Sun | keep-weekly |
| 2026-10-18 | Sun | keep-weekly |
| 2026-09-30 | Wed | keep-monthly |
| 2026-08-31 | Mon | keep-monthly |
That is 16 survivors out of 100. The three keep-last days are already covered, so keep-daily 7 keeps seven more days (November 9 through 15) on top of them. keep-weekly 4 skips the two ISO weeks that already hold a kept snapshot and keeps the Sundays of the four weeks before them. keep-monthly 3 skips November and October, keeps the last snapshot of September and of August, and runs out of history before July, so it adds only two. This follows the selection logic in PBS’s prune.rs. The PBS prune simulator uses the same rules: it is a page in the docs where you enter a backup schedule and retention options and see what lives and dies. Check your numbers there before you apply anything to a real datastore.
Creating a prune job
Prune runs as its own job object, with its own schedule, namespace scope, and max-depth. The config lives in /etc/proxmox-backup/prune.cfg. Create one:
proxmox-backup-manager prune-job create nightly-prune \ --store store1 \ --ns homelab \ --schedule '01:00' \ --keep-last 3 --keep-daily 7 --keep-weekly 4 --keep-monthly 3Both --schedule and --store are required for create. --max-depth limits how many namespace levels below homelab get pruned (0 means only the namespace itself, leave it out to recurse fully). The other subcommands are list, show, update, run, and remove:
proxmox-backup-manager prune-job listproxmox-backup-manager prune-job run nightly-pruneTo prune one backup group by hand with a dry run first, use the client:
proxmox-backup-client prune host/elsa --dry-run --keep-daily 7 --keep-weekly 4proxmox-backup-client prune host/elsa --keep-daily 7 --keep-weekly 4--dry-run shows what would be removed and deletes nothing. Run it every time you touch retention numbers. Your 2 AM self will thank you.
Job Two: Garbage Collection Actually Frees the Space
Garbage collection (GC) is the job that deletes chunks nobody references anymore. It works per datastore in two phases.
- Mark. GC reads every index file and updates the access time (atime) of every chunk those indexes reference.
- Sweep. GC walks all chunks and compares each atime to a cutoff. Anything older than the cutoff is considered unreferenced and gets deleted.
The cutoff is 24 hours and 5 minutes before the GC started, or the start time of the oldest running backup writer if there is one. Chunks inside that window are not deleted. They show up in the task log as “Pending removals”.
The delay exists because most filesystems mount with relatime, which only updates atime if the file was modified since the last access or the last access was 24 hours ago or more. PBS needs that grace period to tell “touched recently” from “nobody wants this”.
An orphaned chunk keeps whatever atime it had when it was last touched, by the previous GC mark phase or by an upload. So the order of events after you prune a snapshot is:
- Prune removes the snapshot metadata. Disk usage does not change.
- A GC run starts. The mark phase skips the orphaned chunks, since no index references them.
- The sweep deletes every orphaned chunk whose atime is older than the cutoff. Usage drops.
- Orphaned chunks that were touched in the last 24h05m (because GC or a backup ran within the last day) show up as Pending removals and go on a later run.
With a weekly GC schedule, the chunks are about a week old by the time GC runs, so the space usually comes back on the next run. If you ran GC by hand an hour ago, the next run frees little. Weekly GC is what the docs suggest as a starting point for most setups.
The trap is thinking that prune frees disk. It does not. Prune frees metadata, and GC frees the data.
Scheduling and checking GC
Set the schedule on the datastore:
proxmox-backup-manager datastore update store1 --gc-schedule 'sat 04:00'To start one now and look at the result:
proxmox-backup-manager garbage-collection start store1proxmox-backup-manager garbage-collection status store1proxmox-backup-manager garbage-collection listlist shows GC status for every datastore, including ones without a GC job. To turn the schedule off during maintenance or before you archive a datastore, delete the property:
proxmox-backup-manager datastore update store1 --delete gc-scheduleThere are advanced --tuning options for GC too: gc-atime-safety-check (on by default, and the docs recommend leaving it on, because it checks that your filesystem handles atime updates correctly), gc-atime-cutoff, and gc-cache-capacity (default 1048576 cache slots). gc-cache-capacity trades memory for GC speed on a large datastore. Leave gc-atime-cutoff and the safety check alone unless you know how your filesystem handles atime, because the cutoff decides which chunks get deleted.
One more caution from the docs: a pruned snapshot’s data lives on until GC removes the chunks. If a secret ended up in a backup, prune the snapshots and run GC to get it off the disk. If GC touched those chunks within the last day, it takes a second run after the grace period.
Calendar Events: The Schedule Syntax
All three jobs take the same schedule format:
[WEEKDAY] [[YEARS-]MONTHS-DAYS] [HOURS:MINUTES[:SECONDS]]Weekdays are mon to sun. Fields accept comma lists (01,02), ranges (01..10), and repetition (05/10 means starting at 5, every 10). If the time is omitted, midnight is implied. The shortcuts are minutely, hourly, daily, weekly (Monday 00:00), monthly, yearly, quarterly, and semiannually. Some examples:
daily every day at 00:00sat 04:00 Saturdays at 04:00mon..fri 8..17,22:0/15 every 15 min, working days, 8:00-17:59 and 22:00-22:59*:00/5 every five minutesStagger the jobs. Run prune at 01:00, GC on Saturday at 04:00, and verify in the morning, so they do not fight over the same disks.
Job Three: Verify Catches Bit Rot Before Restore Day
A backup you cannot restore is a very large file with a hopeful name. Verify jobs read the chunks and check them against their checksums. They also catch a missing or corrupt chunk while you can still do something about it.
Verification has two knobs worth understanding:
ignore-verified(default true) skips snapshots that already passed, as long as the verification is not outdated.outdated-afteris the re-verify interval in days. After that many days, a passed snapshot counts as outdated and gets checked again. The docs say 0 is deprecated.
The docs recommend re-verifying everything at least monthly, because drives degrade over time and an old good backup can rot. Their suggested layout: a frequent job (hourly or daily) that checks new and outdated snapshots, plus a weekly or monthly job that reverifies everything.
Create the frequent job:
proxmox-backup-manager verify-job create daily-verify \ --store store1 \ --ns homelab \ --schedule '06:00' \ --ignore-verified true \ --outdated-after 30--store is the only required option. Threads default to 1 reader and 4 verifiers, adjustable from 1 to 32 with --read-threads and --verify-threads. Add a second job with --ignore-verified false and a weekly or monthly --schedule if you want the full re-read, or run one by hand:
proxmox-backup-manager verify store1 --read-threads 1 --verify-threads 4 --ignore-verified falseproxmox-backup-manager verify-job listproxmox-backup-manager verify-job run daily-verify“Verify new snapshots after completion”
This is a datastore option, verify-new. When on, every backup is verified right after it finishes. You can set it from the CLI:
proxmox-backup-manager datastore update store1 --verify-new trueThe verification runs as a separate verify task that starts as soon as the backup finishes, and the backup task does not wait for it. That task reads every chunk the new snapshot references, including chunks shared with older snapshots, so on spinning disks it adds read load that overlaps with the rest of the backup window. The upside is that you learn about a bad write the same night, not at the next scheduled verify. For a small homelab on decent disks, turn it on. For a large HDD pool, skip it and rely on the daily verify job.
By default PBS iterates chunks for verify in inode order, which suits spinning disks. On NVMe the docs say sorting can cost more than it saves, and you can switch it with --tuning 'chunk-order=none'.
Where Sync Jobs Fit
A sync job copies snapshots between PBS datastores. It can pull from a remote or local datastore into yours, or, since PBS 3.3, push your snapshots to a remote PBS. That is how you get a second copy off the main box, which no amount of verification replaces. Remember that a synced datastore is still a datastore: it needs its own prune, GC, and verify schedule, or it fills up too.
The Whole Setup in One Pass
proxmox-backup-manager datastore create store1 /backup/disk1/store1proxmox-backup-manager datastore update store1 --gc-schedule 'sat 04:00' --verify-new trueproxmox-backup-manager prune-job create nightly-prune --store store1 --schedule '01:00' \ --keep-last 3 --keep-daily 7 --keep-weekly 4 --keep-monthly 3proxmox-backup-manager verify-job create daily-verify --store store1 --schedule '06:00' --outdated-after 30The prune job config ends up in /etc/proxmox-backup/prune.cfg, and the datastore settings in datastore.cfg. A prune job entry looks roughly like this:
prune: nightly-prune keep-daily 7 keep-last 3 keep-monthly 3 keep-weekly 4 schedule 01:00 store store1Prefer the CLI or the GUI over hand edits: they validate the values and guard against concurrent edits.
The practical rhythm: prune nightly, GC weekly, verify daily with a 30-day re-verify interval. Then check the GC task log after the next weekly run: the removed chunks and any Pending removals are listed at the end.
Common Questions
Does pruning in Proxmox Backup Server free disk space immediately?
No. Pruning removes only snapshot metadata. The data chunks stay on disk until garbage collection deletes them. Garbage collection skips chunks whose access time is less than 24 hours and 5 minutes old, so if GC ran within the last day, the space returns only on a later GC run.
How often should I run garbage collection and verify jobs?
Run garbage collection weekly, which the PBS docs suggest as a starting interval. Run a verify job daily with ignore-verified on, and set outdated-after to about 30 days so every snapshot gets re-checked at least monthly, as the docs recommend.
What hardware does a Proxmox Backup Server datastore need?
The PBS docs recommend a modern 64-bit CPU with at least 4 cores, 4 GiB of RAM plus 1 GiB per TiB of storage, and fast local storage with high random IOPS. Enterprise SSDs work best. If you use HDDs, add a metadata cache such as a ZFS special device mirror.
Do I need a subscription to use prune, garbage collection, and verify?
No. These jobs are part of PBS itself and work with the no-subscription repository. A subscription adds access to the enterprise repository and support, but no maintenance job depends on it.
Can I change retention later without losing the backups I want?
Yes, but pruning is permanent. Test new keep settings with proxmox-backup-client prune --dry-run or the prune simulator first. A loosened policy cannot bring back snapshots that an earlier policy already pruned.