qemu-img & qemu-nbd - KVM CLI Tools for Administrators

qemu-img & qemu-nbd – KVM CLI Tools for Administrators

Gedion Kiprotich
October 6, 2025
9:45 am
No Comments

As a manager of the KVM virtual machines, you may need to execute certain operations over image files. Whether it’s for making a backup, adding metadata or moving a bunch of files without having to worry about the NTFS file system deadlocking your process (which make recovering from an OOM even more difficult), when you need to do anything with VHD blobs, either creating them out of thin air or converting them for another use like resizing them for instance – two very powerful command-line utilities come to light: qemu-img and qemu-nbd.

qemu-img is the standard tool used for disk image creation and manipulation formats, such as qcow2, raw, vmdk etc. It’s a console-based application, so everything can be done without requiring to fire up a VM first: it permits you to clone, resize, convert and even verify the integrity of your images.

qemu-nbd does the opposite, serving disk images as block devices over the Linux Network Block Device (NBD) protocol. This allows you to attach VM disks directly within the host and manage them on file level such as backups or restore operations.

Collectively, these tools offer a flexible and performant solution for VM storage at scale. Let’s take a close look at some useful applications, commands, and best practices for using qemu-img and qemu-nbd with KVM in this guide.

🔥 TRENDING - Our #1 Selling eBook

Mastering KVM Virtualization - The Ultimate eBook

From home labs to production clouds - master KVM Host management, automating KVM administration using Terraform, Vagrant, and cloud automation. This eBook will enable you to build scalable virtual infrastructure that works whether you're learning at home or deploying enterprise solutions. Get your full copy today

Only $10 $20

Get Instant Access →

1. Qemu-img – Create, Resize and convert VM images

qemu-img is a command-line tool for creating, converting, and inspecting virtual machine disk images. It supports various image formats, including QCOW2, RAW, VDI, VMDK, and more.

Example 1: Create a New Image

Let us create an image in the default libvirt storage pool path.

sudo qemu-img create -f qcow2 /var/lib/libvirt/images/deb12.qcow2 20G

-f qcow2: Specifies the image format (QCOW2 is a common format for QEMU/KVM).
20G: Creates a 20GB virtual disk.

A virtual machine that uses the disk image can be created using virt-install

sudo virt-install \
--name debian12 \
--ram 4096 \
--vcpus 2 \
--disk path=/var/lib/libvirt/images/deb12.qcow2 \
--os-variant debian12 \
--network bridge=virbr0 \
--graphics none \
--console pty,target_type=serial \
--location /var/lib/libvirt/images/debian-12.7.0-amd64-DVD-1.iso \
--extra-args 'console=ttyS0,115200n8'

Installation will start in text mode.

...

  ┌───────────────────────┤ [!!] Select a language ├────────────────────────┐
  │                                                                         │
  │ Choose the language to be used for the installation process. The        │
  │ selected language will also be the default language for the installed   │
  │ system.                                                                 │
  │                                                                         │
  │ Language:                                                               │
  │                                                                         │
  │                               C                                         │
  │                               English                                   │
  │                                                                         │
  │     <Go Back>                                                           │
  │                                                                         │
  └─────────────────────────────────────────────────────────────────────────┘





<Tab> moves; <Space> selects; <Enter> activates buttons

Example 2: Resize an Image

We can resize an image by adding extra 10GB to it using resize command option:

qemu-img resize /var/lib/libvirt/images/deb12.qcow2 +10G

Example 3: Inspect an Image

The qemu-img info command provides detailed information about a virtual machine disk image, including its format, size, and metadata.

qemu-img info /var/lib/libvirt/images/deb12.qcow2

Example 4: Converting between image formats

It is generally straightforward to convert images from one format to another using qemu-img

The qemu-img convert command can do conversion between multiple formats, including qcow2, qed, raw, vdi, vhd, and vmdk.

Image format	Argument to qemu-img
QCOW2 (KVM, Xen)	`qcow2`
QED (KVM)	`qed`
raw	`raw`
VDI (VirtualBox)	`vdi`
VHD (Hyper-V)	`vpc`
VMDK (VMware)	`vmdk`

Refer to the examples below to learn how image conversion can be done from one format to the other.

Example 5: Grow image / filesystem

Get default filesystem disk size using qemu-img:

IMAGE=ubuntu-24.04-amd64.img
qemu-img info $IMAGE

In the output, we can confirm the disk size before growing it.

image: ubuntu-24.04-amd64.img
file format: qcow2
virtual size: 3.5 GiB (3758096384 bytes)
disk size: 581 MiB
cluster_size: 65536
Format specific information:
    compat: 1.1
    compression type: zlib
    lazy refcounts: false
    refcount bits: 16
    corrupt: false
    extended l2: false
Child node '/file':
    filename: ubuntu-24.04-amd64.img
    protocol type: file
    file length: 581 MiB (608755712 bytes)
    disk size: 581 MiB

Suppose we want to grow disk size by 20GB

qemu-img resize $IMAGE +20G

Confirmation after the change:

$ qemu-img info $IMAGE
image: ubuntu-24.04-amd64.img
file format: qcow2
virtual size: 23.5 GiB (25232932864 bytes)
...

The -f format flag is optional. If omitted, qemu-img will try to infer the image format.

Convert a raw image file to a qcow2 image file.

qemu-img convert -f raw -O qcow2 image.img image.qcow2

convert a vmdk image file to a raw image file.

qemu-img convert -f vmdk -O raw image.vmdk image.img

Convert a vmdk image file to a qcow2 image file.

qemu-img convert -f vmdk -O qcow2 image.vmdk image.qcow2

Convert qcow2 to vdi

qemu-img convert -O vdi test.qcow2 test.vdi

Convert qcow2 to raw

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

Convert qcow2 to vmdk

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

2. Qemu-nbd – Mount and Repair VM disk image

The qemu-nbd command allows you to export and mount virtual machine disk images as block devices using the Network Block Device (NBD) protocol. This functionality enables low-level access to disk images and is useful for inspecting or modifying disk contents, repairing filesystems, or backing up specific partitions.

Command syntax:

qemu-nbd [options] <image>

Commonly used Options

-c <device>: Connect the image to the specified NBD device (e.g., /dev/nbd0).
-d <device>: Disconnect the image from the NBD device.
-f <format>: Specify the image format (e.g., qcow2, raw).
-p <port>: Export the image over a specific port for network access.
--shared: Allow multiple clients to access the NBD device.

Use cases of qemu-nbd

Inspecting and Debugging VM Images:

Mount and inspect filesystems without booting the VM.
Recover data from corrupted disk images.

Backup and Restore:

Export specific partitions for backup.

Testing and Development:

Access block-level data for testing.

Forensics and Security:

Analyze disk images for malware or security breaches.

Qemu-nbd Usage Examples

Here we provide some example to how qemu-nbd command can be used.

Example 1: Export VM disk image as NBD Device

We have an image /var/lib/libvirt/images/deb12.qcow2 that will be exported as /dev/nbd0 device.

The instance domain should be offline.

sudo virsh destroy <domain>

Load NBD Kernel Module using the following command:

sudo modprobe nbd max_part=16

max_part=16 allows up to 16 partitions per NBD device.

You can confirm the module is loaded:

lsmod | grep nbd

After loading the module, the /dev/nbd* devices should appear. Check for their existence:

ls /dev/nbd*

Export the image on /dev/nbd0

sudo qemu-nbd -c /dev/nbd0 /var/lib/libvirt/images/deb12.qcow2

c or --connect is used to connect filename to NBD device.
Image format can be specified using -f command option. For example, -f qcow2

Example 2: Repair / Recover qcow2 image using fsck

List partitions in the image exported.

$ sudo fdisk -l /dev/nbd0
Disk /dev/nbd0: 20 GiB, 21474836480 bytes, 41943040 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x237d6854

Device      Boot    Start      End  Sectors  Size Id Type
/dev/nbd0p1 *        2048 39942143 39940096   19G 83 Linux
/dev/nbd0p2      39944190 41940991  1996802  975M  5 Extended
/dev/nbd0p5      39944192 41940991  1996800  975M 82 Linux swap / Solaris

You can perform filesystem check and repair if any errors existed.

sudo fsck /dev/nbd0p1

To mount a specific partition, use the mount command

sudo mount /dev/nbd0p1 /mnt

Confirm it is mounted using df -hT

$ df -hT /mnt/
Filesystem     Type  Size  Used Avail Use% Mounted on
/dev/nbd0p1    ext4   19G  4.4G   14G  25% /mnt

The files on the VM partition can now be accessed and copied to a safe place if you need to backup.

ls /mnt

Example 3: Disconnecting NBD device

To disconnect the device, first unmount if mounted.

sudo umount /mnt

Then disconnect device, use -d or --disconnect command option.

sudo qemu-nbd --disconnect /dev/nbd0

You should get the message:

/dev/nbd0 disconnected

Aftet the disconnection, virtual machine can be started

virsh start <VM-Name>

Example 4: Exporting VM image over a Network

It is possible to export the image over a network for remote access. In this example it’s exported on TCP port 10900:

sudo qemu-nbd -p 10809 /var/lib/libvirt/images/deb12.qcow2

where:

-p, --port=PORT is the TCP port to listen on as a server, or connect to as a client (default 10809).

To access NBD device from a remote machine, use nbd-client to connect. It can be installed like below:

Debian-based systems

sudo apt update && sudo apt install nbd-client

RHEL-based systems

 sudo dnf install epel-release -y
 sudo dnf install nbd -y

Use nbd-client on a remote machine to connect:

sudo nbd-client <server-ip> 10809 /dev/nbd0

Output sample:

Negotiation: ..size = 20480MB
Connected /dev/nbd0

Validate it exist:

sudo fdisk -l /dev/nbd0

Example 5: Access vm image as read only

To serve a read-only copy of a guest image over a Unix socket, use

sudo qemu-nbd -c /dev/nbd0 --read-only /path/to/image.qcow2

Join our Linux and open source community. Subscribe to our newsletter for tips, tricks, and collaboration opportunities!

Unlock the Right Solutions with Confidence

At CloudSpinx, we don’t just offer services - we deliver clarity, direction, and results. Whether you're navigating cloud adoption, scaling infrastructure, or solving DevOps challenges, our seasoned experts help you make smart, strategic decisions with total confidence. Let us turn complexity into opportunity and bring your vision to life.

Elearning

Cloud Services

Infra Services

Iac & GitOps

IT Support

InfoSec

Development