qemu-img resize disk.qcow2 +10G+ grow the filesystem inside the guest
qemu-img snapshot -l/-c/-a/-d disk.qcow2snapshots (on a shut-down VM)
Overview
qemu-img manages virtual machine disk images (kvm-libvirt). The most
common format is qcow2: thin provisioning (grows as data is written),
snapshots, overlay chains.
bash
qemu-img info disk.qcow2 # format, virtual/actual size, backing file
qemu-img info --backing-chain vm.qcow2 # the whole overlay → backing chain
qemu-img create -f qcow2 disk.qcow2 20G # create an empty 20GB qcow2 image
qemu-img check disk.qcow2 # check the image's integrity
Options
8
-f/-F set the format of the source and the backing image — almost
always qcow2; a mismatch between the declared format and the file's real
content corrupts the image silently, until the first read of the affected
block. -O is the format of the destination image during conversion —
easy to confuse with -f (the source format). -b links an overlay to its
backing file at creation time; changing that link afterward is what
rebase is for.
Show the whole overlay-to-backing chain instead of a single file.
qemu-img info --backing-chain vm.qcow2
-u
rebase: unsafe mode — change the backing reference without checking data. dangerous
qemu-img rebase -u -b "" vm1.qcow2
-p
Show a progress indicator for a long-running operation.
qemu-img convert -p -O qcow2 src dst
Nothing found. Try a shorter query.
Recipes
2
Overlays and conversion
bash
# an overlay on top of a "golden" image (a fast clone, only the delta is written to the overlay)
qemu-img create -f qcow2 -F qcow2 -b golden.qcow2 vm1.qcow2
# format conversion
qemu-img convert -O qcow2 disk.raw disk.qcow2 # raw → qcow2
qemu-img convert -O raw disk.qcow2 disk.raw # qcow2 → raw
qemu-img convert -c -O qcow2 src.qcow2 small.qcow2 # -c: compress while converting# resizing (grow the filesystem inside afterward — see filesystems)
qemu-img resize disk.qcow2 +10G
# "flatten" an overlay into a standalone image (bake in the backing data)
qemu-img convert -O qcow2 vm1.qcow2 vm1-flat.qcow2
# or re-point the overlay at a different backing file:
qemu-img rebase -b new-base.qcow2 vm1.qcow2
qemu-img rebase -u -b "" vm1.qcow2 # safely "detach" it (unsafe mode) — be careful
Snapshots (internal)
bash
qemu-img snapshot -l disk.qcow2 # list internal snapshots
qemu-img snapshot -c snap1 disk.qcow2 # create one (the VM must be shut down!)
qemu-img snapshot -a snap1 disk.qcow2 # revert to it
qemu-img snapshot -d snap1 disk.qcow2 # delete it
For running VMs, take snapshots through virsh snapshot-* (see
kvm-libvirt), not qemu-img against a live image.
Troubleshooting
5
SymptomCause and fix
The image is larger than it should be
qcow2 doesn't shrink itself after data is deleted inside it. Compact it:
qemu-img convert -O qcow2 disk.qcow2 small.qcow2 (the rewrite removes the
"holes"; add -c to compress).
Backing file has changed / the overlay is broken
An overlay is tightly bound to its backing image. Don't change, delete, or
move the backing file while an overlay depends on it. Check the chain:
qemu-img info --backing-chain; re-link it with rebase.
You resized the disk, but the VM has no extra space
qemu-img resize only changes the container. Inside the guest, grow the
partition and filesystem yourself (filesystems / lvm).
Don't touch a mounted/in-use image
Never run qemu-img against a running VM's disk — you'll corrupt it. Shut
the VM down first (virsh shutdown, see kvm-libvirt).
The image is "corrupted" after a crash
qemu-img check disk.qcow2 (and -r all to attempt a repair). Risky
without a backup.
Danger zone
Danger. Never run qemu-img against a running VM's disk: the
hypervisor and qemu-img write to the file independently, and the
result is a corrupted image. Shut the VM down first (virsh shutdown,
see kvm-libvirt).
qemu-img rebase -u changes an overlay's link to its backing file
without touching the data or checking compatibility — it's meant for
cases where you're certain the new backing file holds the same data. A
mistaken rebase -u makes the overlay unreadable, with no explicit error
at the time the command runs. qemu-img convert overwrites the
destination file entirely, with no confirmation prompt.
See also
kvm-libvirt — Virtual machines on Linux — managed with virsh, networks, storage, console.