qm-cleanup: Clean up resources after QEMU/KVM VMs

qm-cleanup: Clean up resources after QEMU/KVM VMs

Overview

  • Purpose: Clean up resources (tap devices, VGPUs, etc.) that Proxmox QEMU/KVM leaves behind after a VM stops.
  • When to run: After a VM shuts down gracefully, crashes, or is forcibly stopped.
  • Why it matters: Prevents resource leaks that can block new VMs or cause networking issues.

Syntax

qm cleanup <vm_id> <clean-shutdown> <guest-requested>

Parameters

  • vm_id: The numeric VM ID you want to clean up.
  • clean-shutdown: Whether to perform cleanup as if a clean shutdown occurred. Use true/false depending on your scenario.
  • guest-requested: Whether the guest requested the cleanup. Use true if the guest OS asked for it; false if you’re cleaning up after a crash or manual stop.

Examples

Basic cleanup after a clean shutdown

qm cleanup 101 true true

Cleanup without guest shutdown request (e.g., after a crash)

qm cleanup 102 false false

Combined scenario: ensure resources are freed after a VM with a specific shutdown mode

qm cleanup 305 true false

Common pitfalls

  • Misinterpreting guest-requested: If you pass true when the guest didn’t request it, you might influence how the cleanup behaves in some configurations. When in doubt, set guest-requested to false for post-crash cleanups.
  • Not cleaning up after crashes: If a VM crashes or is killed, resources may linger until you run cleanup explicitly.
  • Treating vm_id as a string: Use the numeric ID; quotes are optional but mixing types can lead to parsing errors in scripts.

Tips for scripting

  • Validate VM existence first: Check that the VM ID exists in your Proxmox host before running cleanup.
  • Use in automation: Combine with VM shutdown hooks or monitoring to automatically call qm cleanup when a VM stops unexpectedly.

Quick sanity check

  • After cleanup, verify no leftover tap devices or VGPU allocations remain that could block future VMs.
  • Review Proxmox docs for qm.1 to understand any environment-specific flags or caveats: https://pve.proxmox.com/pve-docs/qm.1.html

See Also