LinuxCommandLibrary

qm-disk-import

Import a disk image into a VM

TLDR

Import a VMDK/qcow2/raw disk image using a specific storage name

$ qm [[di|disk]] [[i|import]] [vm_id] [path/to/disk] [storage_name] --format [qcow2|raw|vmdk]
copy

SYNOPSIS

qm-disk-import vmid source-file target-storage [OPTIONS]

PARAMETERS

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

source-file
    The absolute path to the disk image file (e.g., .raw, .qcow2, .vmdk) on the Proxmox host to be imported.

target-storage
    The ID of the Proxmox storage pool or volume group where the new disk will be created and stored.

--format <fmt>
    Specifies the target disk image format for the imported disk (e.g., raw, qcow2). If omitted, the default format of the target storage is used.

--disk <disk_id>
    Assigns a specific PCI/SCSI/SATA ID to the new disk (e.g., scsi0, sata1). If not specified, Proxmox automatically assigns the next available ID.

--sparse
    Attempts to create a sparse file if the target storage supports it, meaning only blocks with data are allocated, saving space.

--lvmthin-max-size <GB>
    For LVM-Thin storage, sets a maximum size for the imported volume, allowing for over-provisioning if desired.

--raw-format <fmt>
    Specifies the original format of the source file, particularly useful if the file extension does not accurately reflect its content (e.g., a .raw file that is actually a QCOW2 image).

DESCRIPTION

The qm-disk-import command is a crucial utility within the Proxmox Virtual Environment (PVE) for importing existing disk images into a virtual machine's storage. It facilitates the migration of virtual disks from other hypervisors or raw disk files directly into Proxmox-managed storage. The command handles various disk image formats, such as RAW, QCOW2, and VMDK, automatically converting them to the appropriate format for the target storage type (e.g., LVM, ZFS, file-based).

This tool simplifies the process of attaching new disks to a VM or replacing existing ones, abstracting away the complexities of manual format conversions and storage provisioning. It's commonly used when moving VMs from other platforms, or when preparing pre-built disk images for use within Proxmox.

CAVEATS

  • Disk Space: Ensure the target-storage has sufficient free space for the imported disk, especially if converting to a non-sparse format.
  • Import Time: Importing large disk images can take a significant amount of time, depending on disk size, storage speed, and server load.
  • VM State: It's generally recommended to perform disk imports while the target VM is powered off to avoid potential data corruption or inconsistencies.
  • Format Compatibility: While the command handles many formats, ensuring the source disk image is healthy and compatible with QEMU/KVM is crucial.

TYPICAL WORKFLOW

A common use case involves downloading a pre-built VM image (e.g., an appliance from a vendor), converting it to a raw or qcow2 format if necessary (e.g., using qemu-img convert), copying it to the Proxmox host, and then using qm-disk-import to attach it to a new or existing VM.

STORAGE TYPES

The command adapts its behavior based on the target-storage type. For LVM, it creates an LVM volume; for ZFS, a ZFS dataset; and for directory-based storage, a file on the filesystem.

HISTORY

The qm-disk-import command is an integral part of the Proxmox Virtual Environment (PVE) suite, which originated in 2007. As Proxmox VE evolved into a comprehensive virtualization and container platform, tools like qm-disk-import were developed to simplify common administrative tasks, such as migrating virtual machines from other hypervisors or integrating pre-built images. Its inclusion reflects Proxmox's focus on ease-of-use and robust management of heterogeneous disk formats and storage backends.

SEE ALSO

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

Copied to clipboard