Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Qemu-img Cheatsheet

This is a cheatsheet/reference for all the qemu-img related commands.

Image File Querying

Get Output in JSON

If you are writing code that interacts with qemu, then you'll be pleased to know they added the following optional parameter to their commands:

  --output=json

Get Information About A File

qemu-img info $FILENAME

For a Qcow2 file this may output:

image: test-guest.qcow2
file format: qcow2
virtual size: 20G (21474836480 bytes)
disk size: 196K
cluster_size: 65536
backing file: /media/ssd_storage2/kvm/vms/templates/template-ubuntu-docker2/head.qcow2
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

For a raw file it may output:

image: images.programster.org.img  
file format: raw  
virtual size: 30G (32217432064 bytes)  
disk size: 30G 

Get Full Chain

Any number of images can be backing a qcow2 file you are looking at. In order to find out where these files are and other information about them you can run:

qemu-img info --backing-chain $FILENAME

Example output:

image: test-guest.qcow2
file format: qcow2
virtual size: 20G (21474836480 bytes)
disk size: 196K
cluster_size: 65536
backing file: /media/ssd_storage2/kvm/vms/templates/template-ubuntu-docker2/head.qcow2
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

image: /media/ssd_storage2/kvm/vms/templates/template-ubuntu-docker2/head.qcow2
file format: qcow2
virtual size: 20G (21474836480 bytes)
disk size: 1.1G
cluster_size: 65536
backing file: /media/ssd_storage2/kvm/vms/templates/template-ubuntu-docker2/base.qcow2
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

image: /media/ssd_storage2/kvm/vms/templates/template-ubuntu-docker2/base.qcow2
file format: qcow2
virtual size: 20G (21474836480 bytes)
disk size: 8.8G
cluster_size: 65536
Format specific information:
    compat: 1.1
    lazy refcounts: true
    refcount bits: 16
    corrupt: false

Image File Manipulation

Convert Raw Image to Qcow2

qemu-img convert \
  -f raw \
  -O qcow2 \
  $INPUT_FILE \
  $OUTPUT_FILE 

Resize/Expand Disk Image

Refer here.

Merge Image Into Its Backing File - Commit


7ZlLc5swEMc/jY/JWLxMjrGbtId0JjOZaZujDALUCESE/OqnrwQSIMApk4dDM/HF6C9pJXZ/Wq3HM3uV7r8ymCffaYjIzJqH+5n9ZWZZwLE88SWVQ6UsFotKiBkO1aBGuMN/kBLnSt3gEBXGQE4p4Tg3xYBmGQq4oUHG6M4cFlFirprDGPWEuwCSvvoThzypVN9aNPo3hONErwy8i6pnDYOHmNFNptabWXZUfqruFGpb6kWLBIZ015Lsq5m9YpTy6indrxCRvtVuq+ZdH+mt981QxsdMsKoJW0g2SO+43Bc/aF+ICcLtorHcJZijuxwGsmcnIi+0hKdEtIB4hEVexSLCeyTsL+uXk70xgYWMylw8BzTFgXouOKMPtZddoUSYkBUllJXrS/9ZQSB1mnGFCvDrma2Robf2XE+NvIYpJhK/H4iFMIPagHoxuTSBa0RuaYE5ppnQAuE0JGwtt4hxLGi46QxIcRjK2UtIcDw441J11COVf0U32h+NEagjL04Uoini7CCGqAm2o2BRhwm4qr1r0NRS0qJSa1Adhri23AAhHhQTw3zYfRxCcVJUkzKe0JhmkFw16rLEXwJQOrkFCNpj/kvK565q3eueTOyr1SWb9xqQNkW/EecHBQHccCqkZhM3lOZqnEmVNUDP5BiRjjUIKeiGBUpyVBKELEY6vKM5YohAjrem9ZdQ4Uw/a4QQ+dGorOEFPlpHUyTiVbOGdcKs4U6fj8gP0LhbZe27jjv/8HzYrnsyPrwRfGThpSzkpDtkjGVk21gYFPw72z91wRy/liYX8SfvCKt/RzijqRgZ9dFXiVrhlmKxcA1dbUcnpUWHpup91Kx23doxZM87hqyOocoLPUMlmfVrj4J1MQCrR4RfliHeGtB6jxtZt5d8nBUlfZdiAPDzfRlB3S+3qeLbiARFvD3Ei+X3Ghbo/DGgu3pRsd1y3aq/d25EQuCdk2IktIxmqJMNlTSexaGMbRZ9o3L0ySuyV8iaNWe6Fvf6WRPMBw5Ql8/npE3/PUnUS0mTz1yrMpQgGPaQrqyaK32S/q6kg059sOjXj29G+sWHIL3IYF4klJ8BV7jPB65tfyI/YeQBcM2iYiC518fitZHXdt+4KD4Wg06oJlLeTqZwdYB9bsJhP7d0HTA1f7PiFYAeVSuappiXbmou4v870ZwU6ldINA5wTACsgSpS/0p+YaIRzebvhIqg5j8b++ov">
base.qcow2
[Not supported by viewer]
head.qcow2
[Not supported by viewer]
snapshot-1523781533
[Not supported by viewer]
Commit head.qcow2
Commit head.qcow2

Let's say that you have two files called head.qcow2 and base.qcow2 that backs it. If you wish to merge the two, then use the qemu-img commit which will merge the provided file into its backing image.

qemu-img commit $FILEPATH

e.g.

qemu-img commit head.qcow2

Then you can manually delete head.qcow2 if you like. All you really need now is base.qcow2.

Don't forget to either set up some symlinks or run virsh edit $VM_ID to update the guest to point back to the base.qcow2 rather than head.qcow2.

Change Path Of Backing File

If you have moved the backing file to a new location, then you will need to run this command on the file(s) that were referencing it. This will just update them to point to the new location:

sudo qemu-img rebase \
  -f qcow2 \
  -u \
  -b $NEW_BACKING_FILE_LOCATION \
  $QCOW2_FILE_TO_CHANGE

The -u stands for unsafe and results in a very quick operation of changing the pointer. If you don't specify it, then you will be doing the next section.

Changing Backing File (Advanced)

If you wish to wish to change to use a different backing file which may be different from the current backing file, then you want to use:

sudo qemu-img rebase \
  -f qcow2 \
  -b $NEW_BACKING_FILE \
  $QCOW2_FILE_TO_CHANGE

This can only be run whilst the guest is offline, otherwise you get the following error:
qemu-img: Could not open '908793e8-8f85-4644-ad5c-6dc3afcbf9a2.qcow2': Failed to get "write" lock Is another process using the image [908793e8-8f85-4644-ad5c-6dc3afcbf9a2.qcow2]?

This will be a slower operation as any differences between the original backing file and the new one are merged into $QCOW2_FILE_TO_CHANGE. The result is that the "guest-visible content" remains the same and neither of the backing files are changed. The only file that changes is the "head" or "top" file ($QCOW2_FILE_TO_CHANGE) Obviously, this requires you to still have the original backing file.

This command is actually quite neat/useful as it allows you do do the following:

Collapse/Flatten All Images

Let's say your happy with how your guest's data is, but you're tired of managing all your backing images and just want to start fresh with one image (head.qcow2). The easiest way to do that is to run a block pull

virsh blockpull $GUEST_ID vda --wait

If your guest has multiple images then you will need to repeat for each disk. Add the --delete parameter if you wish for the old images to be removed and you know that no other images might be referencing them.

Internal Snapshots

List Snapshots

qemu-img snapshot -l $DISK_IMAGE.qcow2

Snapshots also appear in the output of the qemu-img info command.

Create Snapshot

qemu-img snapshot -c $SNAPSHOT_NAME $DISK_IMAGE

Restore (Apply) Snapshot

qemu-img snapshot -a $SNAPSHOT_NAME $DISK_IMAGE

Delete Snapshot

qemu-img snapshot -d \
  $SNAPSHOT_NAME \
  $DISK_IMAGE

References

Last updated: 30th April 2024
First published: 16th August 2018

This blog is created by Stuart Page

I'm a freelance web developer and technology consultant based in Surrey, UK, with over 10 years experience in web development, DevOps, Linux Administration, and IT solutions.

Need support with your infrastructure or web services?

Get in touch