qm-wait

Wait until the virtual machine is stopped

$ qm [[w|wait]] [vm_id]

$ qm [[w|wait]] --timeout [10] [vm_id]

$ qm [[shu|shutdown]] [vm_id] && qm [[w|wait]] --timeout [10] [vm_id]

qm-wait <upid> [--timeout <integer>] [--quiet] [--verbose] [--max-log-lines <integer>] [--output-format <json|text>]

upid
    The Unique Process IDentifier of the task to wait for. This is a string identifying a background task on a Proxmox VE node.

--timeout <integer>
    Maximum number of seconds to wait for the task to complete. If the task does not finish within this period, the command will exit with a timeout error.

--quiet
    Suppress normal success messages. Only error messages are printed.

--verbose
    Print more detailed information about the task's progress and status during the wait.

--max-log-lines <integer>
    When the task fails, display up to this many lines from the end of the task log.

--output-format <json|text>
    Define the output format for the final result of the UPID. Can be json or text.

qm-wait is a utility command used within Proxmox VE environments. Its primary function is to block execution until a specified background task (identified by its Unique Process IDentifier, or UPID) has completed. This is particularly useful in scripting and automation where subsequent actions depend on the successful or failed completion of a VM or container operation (e.g., starting, stopping, migrating, or backing up a VM/CT). The command monitors the status of the given UPID, exiting successfully (return code 0) once the task finishes, or with an error code if the task fails, times out, or the UPID is invalid. It allows for robust error handling and sequential task management in Proxmox scripts.

qm-wait relies on the UPID being valid and existing. If the UPID is incorrect or the task has already completed/disappeared from the task history, qm-wait might exit immediately or report an error. It is a blocking command, so in scripts, ensure proper timeout handling to prevent indefinite waiting. This command is specific to Proxmox VE environments.

A Unique Process IDentifier (UPID) is a unique string that identifies a background task in Proxmox VE. It typically has the format UPID:node:timestamp:taskid:user@realm:vmtype:vmid:command:. Commands like qm start or pct migrate return a UPID, which can then be passed to qm-wait to monitor its completion.

qm-wait is invaluable for scripting automated Proxmox VE tasks. For instance, after initiating a VM migration with qm migrate (which returns a UPID), a script can use qm-wait with that UPID to ensure the migration is complete before attempting subsequent actions like VM power-off or backup. This ensures proper sequencing and error handling in automated workflows.

qm-wait is an integral part of the Proxmox VE suite, a leading open-source virtualization management solution. It emerged as a necessary utility to manage asynchronous operations (like VM starts, migrations, backups) which are handled as background tasks identified by UPIDs. Its development is deeply tied to Proxmox's robust task management system, enabling reliable automation and scripting of long-running operations within the Proxmox ecosystem.

qm(1), pct(1), pvesh(1)