qm-disk-move
Move virtual machine disk images
TLDR
Move a virtual disk
Delete the previous copy of the virtual disk
SYNOPSIS
qm-disk-move <vmid> <disk> <target-storage> [OPTIONS]
Example: qm-disk-move 100 scsi0 local-lvm --format qcow2 --bwlimit 102400
PARAMETERS
<vmid>
The ID of the virtual machine whose disk is to be moved.
<disk>
The identifier of the disk to be moved (e.g., scsi0, ide1, virtio0).
<target-storage>
The ID of the Proxmox storage pool where the disk will be moved.
--bwlimit <integer>
Limits the bandwidth for the disk move operation in kB/s. Useful to prevent excessive network or storage load during transfers.
--delete-old-disk <boolean>
Specifies whether the original disk should be deleted from the source storage after a successful move. Defaults to true.
--format <string>
Defines the target image format for the disk (e.g., raw, qcow2, vmdk). If not specified, the original format or a default for the target storage is used.
--sparse <boolean>
Enables or disables sparse allocation for the target disk image. Applicable for formats like qcow2 or vmdk. Defaults to true where supported.
--target-disk <string>
Allows specifying a new disk ID for the moved disk on the target storage (e.g., scsi1). If omitted, the command attempts to reuse the existing disk ID.
--target-node <string>
Specifies a target node for the move operation. Relevant in clustered environments for specific shared storage setups or for offline moves across nodes.
--wait <boolean>
Determines whether the command should wait for the disk move operation to complete before exiting. Defaults to true.
DESCRIPTION
qm-disk-move is a Proxmox VE command-line utility designed to migrate a virtual machine's disk from one storage location to another. This powerful tool allows administrators to efficiently reorganize their storage infrastructure, balance I/O loads, or move disks to different types of storage (e.g., from local to shared, or from HDD to SSD).
The command handles the entire process: it clones the source disk to the specified target storage, updates the VM's configuration to point to the new disk, and optionally deletes the original disk. Depending on the storage types and configuration, the move operation can be performed online (while the VM is running) for certain shared storage configurations, or it might require the VM to be shut down. It provides options to control bandwidth, target format, sparse allocation, and whether the old disk is automatically removed after a successful transfer. This flexibility makes qm-disk-move an essential tool for Proxmox VE storage management.
CAVEATS
- For certain storage types (e.g., local storage) or when moving disks between different Proxmox nodes without shared storage, the virtual machine typically needs to be shut down (offline) before the disk move operation can begin.
- Ensure the target storage has sufficient free space to accommodate the disk, especially if converting to a non-sparse format or a format with a larger overhead.
- If --delete-old-disk is set to false, the original disk will remain, requiring manual cleanup.
- Bandwidth limits (--bwlimit) can significantly extend the time required for the operation, particularly for large disks.
LIVE MIGRATION CONSIDERATIONS
qm-disk-move can sometimes be used for 'live' disk migration (VM remains running) if the underlying storage supports features like shared storage and atomic updates. However, for non-shared storage or specific configurations, it is generally safer and often required that the VM is offline before initiating the disk move.
VM CONFIGURATION UPDATES
When a disk is moved, the virtual machine's configuration file (typically located at /etc/pve/qemu-server/<vmid>.conf) is automatically updated by Proxmox VE to reflect the new disk location and properties. If the --target-disk option is used, the disk ID within the VM configuration will also be updated accordingly.
HISTORY
qm-disk-move is an integral part of Proxmox Virtual Environment (PVE), a Debian-based virtualization management solution. Its development is tied directly to the evolution of PVE, which originated in 2007. As Proxmox VE matured, so did its storage management capabilities, leading to the introduction and refinement of tools like qm-disk-move to facilitate flexible and robust handling of virtual machine disks across various storage backends. It reflects the ongoing need for efficient storage migration in dynamic virtualized environments, enabling administrators to adapt to changing storage requirements without complex manual procedures.