Full Guide to qemu-img convert: Convert, Compress, and Manage Virtual Disk Images

qemu-img convert is a powerful utility for converting virtual disk images between different formats, resizing them, compressing, and even copying them efficiently. Whether you work with KVM, QEMU, VirtualBox, or VMware, understanding this tool can save you time and disk space. Here’s a comprehensive guide for beginners and advanced users alike.

---

What is qemu-img convert?

qemu-img convert is part of the qemu-img suite. Its main function is to convert one disk image format to another, but it can also compress, sparsify, and resize images in the process.

Common formats supported:

• qcow2 (QEMU/KVM native)

• raw

• vmdk (VMware)

• vdi (VirtualBox)

• vhd/vhdx (Microsoft Hyper-V)

• parallels (Parallels Desktop)

---

Basic Syntax

qemu-img convert [options] -O <output_format> <input_image> <output_image>

Examples:

• Convert a raw image to qcow2:

    qemu-img convert -O qcow2 disk.raw disk.qcow2
  

• Convert a vmdk (VMware) to qcow2:

    qemu-img convert -O qcow2 disk.vmdk disk.qcow2
  

---

Common Use Cases

1. Convert Between Formats

• VMware VMDK to QCOW2 (KVM):

    qemu-img convert -O qcow2 source.vmdk dest.qcow2
  

• VirtualBox VDI to RAW:

    qemu-img convert -O raw source.vdi dest.raw
  

• RAW to VHDX (Hyper-V):

    qemu-img convert -O vhdx source.raw dest.vhdx
  

2. Compress Disk Images

Use the -c flag to compress supported formats (like qcow2):

qemu-img convert -c -O qcow2 source.qcow2 dest.qcow2

3. Create a Sparse Image

If your input image is thick provisioned (all blocks allocated), you can make the output sparse (only actual data blocks allocated):

qemu-img convert -O qcow2 thick.qcow2 sparse.qcow2

4. Resize During Conversion

Use the -S (sparsify) option to ignore data blocks with only zeros, making the target image smaller:

qemu-img convert -O qcow2 -S 0 source.qcow2 dest.qcow2

5. Convert and Encrypt Disk Images

You can encrypt the output qcow2 image:

qemu-img convert -O qcow2 --object secret,id=sec0,data=YOURPASSWORD \
  -o encrypt.format=luks,encrypt.key-secret=sec0 source.raw dest.qcow2

Replace YOURPASSWORD with a strong password or use secret files as recommended by QEMU docs.

---

Advanced Examples

Convert and Change Size

You can resize images after conversion with qemu-img resize:

qemu-img convert -O qcow2 source.raw dest.qcow2
qemu-img resize dest.qcow2 100G

Convert Multiple Images (Snapshots)

For images with snapshots or backing files, use --backing-chain to include the entire chain:

qemu-img convert -O qcow2 --backing-chain snap.qcow2 full.qcow2

---

Full List of Key Options

• -O <fmt>: Output format (qcow2, raw, vmdk, vdi, vhdx, etc.)

• -c: Compress the output image (for supported formats)

• -p: Show progress bar

• -S <size>: Sparsify zeros (ignore zeroed blocks above this size)

• -f <fmt>: Input format (auto-detected if omitted)

• --backing-chain: Convert the entire snapshot/backing chain

• -o <options>: Format-specific options (e.g., cluster_size for qcow2, preallocation, encryption)

• -n: Do not create the output file, just test conversion

---

Tips and Best Practices

• Always backup your disk images before converting or overwriting!

• For best compaction, zero-fill free space inside the guest OS before converting (e.g., with dd or SDelete).

• After conversion, use qemu-img info <image> to inspect the result.

• When moving VMs between hypervisors, check for driver and hardware compatibility after conversion.

---

Troubleshooting

• Error: “format not supported”
  Make sure you have the necessary QEMU modules/libraries for your source/target formats.

• Image won’t boot after conversion
  Check that your VM configuration matches the new format (bus type, drivers, etc.)

---

References

• QEMU Documentation: qemu-img

• libvirt Disk Images

---

Conclusion

qemu-img convert is your Swiss Army knife for virtual disk image management—whether you’re migrating between platforms, reclaiming space, or compressing images for backups. Experiment in a safe environment and take regular backups to make the most of this essential tool!