qm-cleanup
Clean up failed or incomplete Proxmox VE tasks
TLDR
Clean up resources
SYNOPSIS
qm-cleanup [OPTIONS]
PARAMETERS
--dryrun, -d
Performs a simulation of the cleanup process, showing which files and configurations would be removed without actually deleting anything. Highly recommended for initial runs.
--verbose, -v
Increases the verbosity of the output, providing more detailed information about the scanning and cleanup process.
--force, -f
Forces the cleanup without requiring user confirmation for deletions. Use with extreme caution.
--storage <storage_id>, -s <storage_id>
Limits the cleanup operation to a specific storage ID, ensuring only orphaned files on that storage are processed.
--keep-days <N>, -k <N>
Specifies the number of days to keep files or configurations that were last modified within this period. Files older than N days are considered for cleanup. Defaults to 7 days.
--keep-locks
Prevents the removal of orphaned lock files.
--keep-orphaned-vmid-config
Prevents the removal of orphaned VM/CT configuration files.
--keep-unused-disks
Prevents the removal of unused disk images.
DESCRIPTION
qm-cleanup is a Proxmox VE utility designed to identify and remove orphaned or stale configuration files, lock files, and disk images associated with virtual machines and containers. These remnants can accumulate due to unexpected system reboots, failed VM/CT operations, or improper removals, leading to disk space wastage and potential inconsistencies. The command helps maintain a clean and efficient Proxmox environment by safely identifying and removing these unreferenced files, ensuring system stability and optimal resource utilization. It's often run with a dry-run first to preview changes before execution.
CAVEATS
- Root Permissions: qm-cleanup must be run as root or with sudo to perform its operations.
- Dry Run First: Always perform a dry run (--dryrun) before executing the command to understand its impact and prevent unintended data loss.
- Permanent Deletion: Files removed by qm-cleanup are permanently deleted and cannot be recovered without backups.
- Specific Purpose: This command is for cleaning orphaned files, not for general disk space management or removing active VM/CT resources.
EXECUTION CONTEXT
This command is specifically designed for Proxmox Virtual Environment installations. It relies on Proxmox's internal configuration and storage management to identify orphaned resources. Running it on a non-Proxmox system will not yield meaningful results.
SAFETY PRACTICES
While qm-cleanup is designed to be safe, it's crucial to regularly back up your Proxmox configuration and critical VM/CT data. The --dryrun option is your first line of defense against accidental deletion.
HISTORY
qm-cleanup is an integral part of the Proxmox VE ecosystem. It was introduced to address the common issue of stale or orphaned files accumulating in virtual environments, especially after crashes, power outages, or incomplete VM/CT deletion operations. Its design reflects the need for automated maintenance in large-scale virtualization deployments, evolving with Proxmox VE versions to improve scanning logic and user control over cleanup actions.