Proxmox Backup Server: Garbage Collection and Prune

Introduction

This tutorial explains how to configure Proxmox Backup Server maintenance for long-term backup storage using prune jobs and garbage collection. You will configure Proxmox Prune configuration, schedule Proxmox Garbage Collection, and estimate storage usage so your datastore does not grow until it consumes all available disk space.

By the end of this tutorial, you will have a scheduled prune policy and garbage collection schedule for a Proxmox Backup Server datastore, with practical retention examples for daily, weekly, and monthly backups.

Prerequisites

Before you begin, make sure you have:

• Proxmox Backup Server 4.2.x or later
• A configured PBS datastore with existing or planned backups
• Administrator access to the Proxmox Backup Server web interface
• Shell access as root or another user with sufficient PBS administration permissions
• A basic understanding of Proxmox VE backup jobs and PBS namespaces
• Approximately 30 minutes to complete the configuration

This tutorial is intended for intermediate system administrators.

Step 1: Understand How Prune and Garbage Collection Work Together

In Proxmox Backup Server, pruning and garbage collection are separate maintenance operations. Understanding how they work together is essential for effective Proxmox datastore management.

A prune job decides which backup snapshots to keep and which snapshots to remove from the visible backup history. When PBS prunes a snapshot, it removes snapshot metadata, indexes, logs, and notes. It does not immediately removing unused backup chunks. The chunks referenced by pruned snapshots are removed later by garbage collection.

Garbage collection (GC) frees datastore space by deleting unused chunks from chunk storage. PBS uses deduplicated chunks, so one chunk can be referenced by multiple backup snapshots. Because of this, PBS cannot safely delete chunks at the exact moment a snapshot is pruned. It must first confirm that no remaining snapshot or running backup still references them.

PBS also uses a grace period for chunk removal. During GC, chunks are marked and swept, but chunks inside the grace period are reported as pending removals and are not deleted immediately. This protects running backups and accounts for filesystem access time behavior, especially with common relatime mount behavior.

Step 2: Review the Current Datastore Configuration

You can do this either through the CLI or the web interface.

List available datastores:

proxmox-backup-manager datastore list

Expected output: datastore list table.

Choose the datastore that stores your Proxmox VE backups. In the following examples, replace <DATASTORE_NAME> with your datastore name.

Check current garbage collection status:

proxmox-backup-manager garbage-collection status <DATASTORE_NAME>

You should see the current GC status for the datastore. If GC has never run, the output may show no previous successful run.

List existing prune jobs:

proxmox-backup-manager prune-job list

You should see existing prune jobs, or an empty list if no prune job has been configured.

To verify it through the web interface, go to Datastore - <DATASTORE_NAME> - Prune & GC Jobs:

Step 3: Plan a Long-Term Backup Retention Policy

A retention policy should match restore requirements and storage capacity. For many Proxmox backup retention plans, a practical long-term policy uses the grandfather-father-son pattern:

Retention option	Example value	Result
keep-daily	14	Keep one backup per day for 14 backup days
keep-weekly	8	Keep one backup per week for 8 backup weeks
keep-monthly	12	Keep one backup per month for 12 backup months
keep-yearly	2	Keep one backup per year for 2 backup years

PBS retention options are processed by time buckets. For example, keep-daily keeps the latest backup for each retained day, and days without backups do not count. keep-weekly keeps the latest backup for each retained ISO week, and weeks without backups do not count.

For a daily backup schedule, start with one of these policies:

Policy	Retention settings	Use case
Conservative	keep-daily 7 keep-weekly 4 keep-monthly 6	Small datastore or short restore history
Balanced	keep-daily 14 keep-weekly 8 keep-monthly 12	Typical VM and container backups
Long-term	keep-daily 30 keep-weekly 12 keep-monthly 24 keep-yearly 3	Larger datastore or compliance-driven history

Step 4: Estimate Backup Storage Before Applying Retention

Storage planning for long-term backup storage is not the same as multiplying full VM size by snapshot count. Proxmox Backup Server uses deduplication, so each new backup usually stores only changed chunks plus metadata. However, you should still calculate a conservative estimate.

Use this formula:

Estimated storage = initial protected data + daily changed data * retained days equivalent + safety margin

Example 1: Balanced retention for a VM group:

Value	Example
Protected VM data	2 TB
Average daily changed data	80 GB
Retention policy	14 daily · 8 weekly · 12 monthly
Safety margin	25 percent

Approximate retained change points:

14 daily + 8 weekly + 12 monthly = 34 restore points

Approximate changed data:

80 GB * 34 = 2720 GB

Approximate total before margin:

2000 GB + 2720 GB = 4720 GB

Add a 25 percent safety margin:

4720 GB * 1.25 = 5900 GB

For this workload, plan for about 6 TB of usable datastore capacity.

Example 2: Smaller datastore policy:

Value	Example
Protected VM data	1 TB
Average daily changed data	30 GB
Retention policy	7 daily · 4 weekly · 6 monthly
Safety margin	25 percent

Approximate restore points:

7 + 4 + 6 = 17 restore points

Approximate storage:

1000 GB + (30 GB * 17) = 1510 GB
1510 GB * 1.25 = 1887.5 GB

For this workload, plan for about 2 TB of usable datastore capacity.

Step 5: Create a Prune Job in the Web Interface

1. Open the Proxmox Backup Server web interface.
2. Select Datastore.
3. Select<DATASTORE_NAME>.
4. Open the Prune & GC tab.
5. Click Add Prune Job.
6. Set Datastore to<DATASTORE_NAME>.
7. Set Namespace if you want to prune only one namespace.
8. Configure retention values, for example keep-daily as 14, keep-weekly as 8, and keep-monthly as 12.
9. Set the schedule, for example 03:00.
10. Save the prune job.

Expected result: PBS creates a scheduled prune job for the datastore or namespace. This job periodically removes backup snapshots that are no longer selected by your retention policy.

Step 6: Create a Prune Job from the Command Line

You can also create the same prune job from the PBS shell.

For a datastore-wide prune job:

proxmox-backup-manager prune-job create pve-longterm \
  --store <DATASTORE_NAME> \
  --schedule "03:00" \
  --keep-daily 14 \
  --keep-weekly 8 \
  --keep-monthly 12 \
  --comment "Long-term Proxmox backup retention"

Expected result: PBS creates a prune job named pve-longterm.

For a namespace-specific prune job:

proxmox-backup-manager prune-job create pve-namespace-longterm \
  --store <DATASTORE_NAME> \
  --ns <NAMESPACE> \
  --schedule "03:00" \
  --keep-daily 14 \
  --keep-weekly 8 \
  --keep-monthly 12 \
  --comment "Long-term retention for namespace"

Expected result: PBS prunes only the selected namespace. This is useful when different clusters, tenants, or environments require different retention policies.

List the prune job:

proxmox-backup-manager prune-job list

Expected output: proxmox backup cleanup job list table.

Step 7: Configure Garbage Collection Scheduling

After pruning removes old snapshot metadata, GC must run to reclaim unused chunk space. A weekly GC schedule is a good starting point for most setups.

Set a weekly GC schedule:

proxmox-backup-manager datastore update <DATASTORE_NAME> \
  --gc-schedule "Sun 04:00"

You can configure it through the web interface by navigating to Datastore - <DATASTORE_NAME> - Prune & GC Jobs → Garbage Collection Jobs → Edit:

Expected result: PBS schedules garbage collection for the datastore every Sunday at 04:00.

Check the GC status:

proxmox-backup-manager garbage-collection status <DATASTORE_NAME>

Expected output includes the datastore name and information about the most recent or next GC run.

You can also start GC manually:

proxmox-backup-manager garbage-collection start <DATASTORE_NAME>

Expected result: PBS starts a GC task for the datastore.

Step 8: Choose a Safe Prune and GC Schedule

A practical schedule is:

Task	Example schedule	Reason
Proxmox VE backup job	Daily at 01:00	Creates new backups first
PBS prune job	Daily at 03:00	Removes snapshots outside retention
PBS GC job	Weekly on Sunday at 04:00	Reclaims unused chunks after pruning

This order keeps new backups available before old snapshots are removed. It also gives PBS time to complete backup writes before prune and GC tasks start.

For busy environments, avoid running backup, verification, prune, sync, and GC tasks at the same time. Stagger maintenance jobs to reduce I/O contention.

Step 9: Verify the Configuration

List prune jobs:

proxmox-backup-manager prune-job list

Confirm that the job has the expected datastore, namespace, schedule, and keep values.

Show one prune job:

proxmox-backup-manager prune-job show pve-longterm

Expected result: PBS displays the configured retention options.

Check GC configuration:

proxmox-backup-manager garbage-collection list

Expected result: PBS lists garbage collection status for all datastores, including datastores without GC jobs.

Check datastore usage from the web interface:

• Open Datastore.
• Select<DATASTORE_NAME>.
• Review datastore usage and task history.
• Open Tasks and confirm prune and GC jobs complete successfully.

Expected result: The datastore shows scheduled maintenance activity, and old snapshots are removed according to the configured Proxmox Prune configuration.

Step 10: Monitor Storage Growth Over Time

After configuring Prune jobs in PBS, monitor storage usage for at least one full retention cycle. For example, if you configure keep-monthly 12, you need several months of data before the long-term trend becomes clear.

Review these metrics:

Metric	What to check
Datastore used space	Confirms whether backup storage optimization is working
Prune task logs	Confirms snapshots are being removed
GC task logs	Confirms unused chunks are being deleted
Pending removals	Indicates chunks waiting for the GC grace period
Backup job size trend	Shows whether changed data is increasing

If the datastore keeps growing faster than expected, reduce retention or add storage before the filesystem becomes full.

Common adjustments:

Problem	Adjustment
Datastore fills too quickly	Reduce keep-daily, keep-weekly, or keep-monthly
Too few recent restore points	Increase keep-daily
Monthly history is too short	Increase keep-monthly
Backups overlap with maintenance	Move prune or GC to a later time
GC frees little space	Confirm prune jobs actually remove old snapshots

Reverting Changes

To remove a prune job:

proxmox-backup-manager prune-job remove pve-longterm

Expected result: PBS removes the prune job configuration.

To disable the GC schedule without deleting the datastore:

proxmox-backup-manager datastore update <DATASTORE_NAME> \
  --delete gc-schedule<datastore_name></datastore_name>

Expected result: PBS clears the automatic GC schedule for the datastore.

To change retention instead of removing the prune job:

proxmox-backup-manager prune-job update pve-longterm \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6

Expected result: PBS keeps the prune job but applies the new retention policy during future prune runs.

Troubleshooting

GC Does Not Free Space Immediately

Cause: Prune removed snapshot metadata, but chunks are still referenced by other snapshots or are inside the GC grace period.
Fix: Wait for the grace period and run GC again later. Check task logs for pending removals.

Prune Keeps More Backups Than Expected

Cause: keep-daily, keep-weekly, and keep-monthly use time buckets. Days, weeks, or months without backups do not count. Retention rules also overlap.
Fix: Use the PBS prune simulator before changing production retention. This helps you preview retention behavior before applying changes.

Datastore Still Grows After Prune and GC

Cause: Daily changed data may be higher than estimated, backups may include new disks, or retention may be too large for the datastore.
Fix: Recalculate the volume estimate using actual changed data. Reduce retention or expand storage.

Prune Job Does Not Affect a Namespace

Cause: The prune job may be configured for the wrong namespace or namespace depth.
Fix: Review the prune job settings and confirm the --ns value. If you want the job to apply only to one namespace, set the namespace explicitly.

Backup Clients Can Still Delete Backups

Cause: Backup credentials may have delete permissions or retention may be configured outside PBS.
Fix: Use least privilege for backup clients. For ransomware resistance, prefer PBS-side prune jobs instead of granting delete permissions to backup clients.

Conclusion

You configured Proxmox Backup Server maintenance for long-term retention by creating a prune job and scheduling garbage collection. You also learned why chunks are not deleted immediately, how GC completes datastore cleanup, and how to estimate storage requirements before applying long-term retention. These practices support Proxmox backup optimization by improving storage efficiency and ensuring that backup retention remains predictable and manageable.

For next steps, add verification jobs, configure notifications for failed prune and GC tasks, and review datastore growth monthly. This keeps backup storage optimization predictable and prevents retention settings from silently consuming all available capacity.

Document Version: 1.0
Last Updated: June 2026
Owner: Technical Documentation Team