qm-import-disk

View documentation for the original command

$ tldr qm disk import

qm import-disk [options]

vmid
    Mandatory. The unique ID of the virtual machine to which the disk will be imported.

source
    Mandatory. The full path to the source disk image file (e.g., /path/to/myvm.qcow2).

storage
    Mandatory. The ID of the Proxmox storage backend (e.g., local-lvm, cephfs, nfs_data) where the new virtual disk will be created.

--format
    Specifies the target disk format for the imported image. Common values include raw, qcow2, or vmdk. If omitted, Proxmox attempts to auto-detect or uses a default based on the storage type.

--sparse
    If set to 1, the imported disk will be created as a sparse file on file-based storage, occupying only the space used by data. Set to 0 for a pre-allocated disk.

--discard
    Enable or disable TRIM/DISCARD support (1 for enabled, 0 for disabled). Recommended for SSDs or thin-provisioned storage to reclaim unused blocks.

--cache
    Sets the caching mode for the disk. Options include none (default), writethrough, writeback, directsync, and unsafe. Choose based on performance and data integrity requirements.

--aio
    Sets the Asynchronous I/O (AIO) mode. Options like native, threads, or io_uring (newer kernels) can affect disk performance.

--size
    Explicitly sets the target size of the imported disk (e.g., 100G, 500M). This is useful when the source image is sparse or needs to be resized.

--id
    Specifies the controller type and index for the new disk (e.g., scsi0, sata1, ide0). If not provided, Proxmox will assign the next available ID.

qm import-disk is a Proxmox VE (PVE) command-line utility designed to import an existing disk image file into a specified virtual machine (VM) within the Proxmox environment. This command is essential for scenarios such as migrating VMs from other virtualization platforms (like VMware, VirtualBox, KVM, etc.), importing pre-configured virtual disk images, or attaching new disk images to existing VMs.

It handles the conversion and placement of the disk image onto Proxmox's various storage types, including LVM, ZFS, directory-based storage, or shared storage like Ceph. The command automates the process of creating a new virtual disk for the VM and copying the data from the source image, offering options to specify the target storage, disk format, and even configure the disk's properties within the VM's configuration. This simplifies the often complex task of bringing external disk data into a Proxmox VM.

Importing large disk images can be time-consuming, depending on the source file size, target storage performance, and chosen format conversion.
The command requires direct access to the source disk image file from the Proxmox host. Ensure adequate free space on the target Proxmox storage before starting the import.
While qm import-disk attaches the new virtual disk to the VM's configuration, the VM typically needs to be stopped and restarted or rebooted for the operating system within the VM to recognize and utilize the newly imported disk.

Upon successful import, qm import-disk automatically adds the newly created virtual disk to the specified VM's configuration. It will attempt to use the next available virtual slot (e.g., scsi0, sata0) unless explicitly specified with the --id parameter. The disk will be visible in the VM's hardware configuration within the Proxmox GUI or via qm config <vmid>.

The import process can be I/O intensive. Factors affecting performance include the speed of the source disk, the network bandwidth (if the source is network-mounted), and especially the throughput of the target Proxmox storage. Using fast storage like NVMe or Ceph can significantly reduce import times.

Proxmox VE, a popular open-source virtualization platform, integrates qm import-disk as a crucial subcommand of its primary VM management utility, qm. This functionality has been available since early versions of Proxmox VE, evolving alongside the platform's growth and its underlying QEMU/KVM virtualization technologies. It became indispensable for system administrators migrating virtual machines from other hypervisors or deploying custom disk images into the Proxmox environment, reflecting the increasing need for flexible VM and storage management in cloud and enterprise setups.

qm(1), qemu-img(1), pvesm(1)