Mounting qcow2 virtual disk images

fuse, disk, qcow2, qemu



This program allows you to mount qcow2 virtual disk images as FUSE filesystems.


Mount a myimage.qcow2 onto the directory mnt with:

qcow2-fuse myimage.qcow2 mnt

The directory will now contain a file mnt/myimage that lets you read the virtual disk contents.

Using the mounted image

Your virtual disk may contain just one partition, in which case you can mount it like a device:

mount mnt/myimage /mnt/myimage

# Or with another FUSE filesystem:
ext4fuse mnt/myimage /mnt/myimage

By default, FUSE filesystems are only available to the current user. If you want to mount the virtual filesystem as root, you'll need to pass the -o allow_root option to qcow2-fuse.


Sometimes your virtual disk contains multiple partitions, so you can't just mount it directly. Instead, ask your OS to take care of reading the partitions:

# On Linux:
kpartx -a mnt/myimage

# On macOS
hdiutil attach -imagekey diskimage-class=CRawDiskImage \
  -nomount mnt/myimage

This will generate new entries in /dev that you can then mount as above.


Several options to this program are available. You can see descriptions of some of them by running qcow2-fuse --help.

Many options starting with -o will be passed through to FUSE. You can read about these options for Linux and for macOS.


The best way to install this right now is using cargo, the Rust package manager.

First, you'll need Rust and Cargo themselves. You can download them here.

Second, you'll need to have FUSE installed, and pkg-config so that we can find it. Here are some examples of how to get those:

  • Ubuntu: sudo apt-get install libfuse-dev pkg-config
  • macOS: Install MacPorts, then sudo port install osxfuse pkgconfig

Finally, you can install this program: cargo install qcow2-fuse


I'll try to make these available when I have the bandwidth.


This program can mount only certain qcow2 images:

  • Only version 3 (aka "qcow2 1.1") is supported; version 2 is not supported.
  • This program provides read-only access, writing is not supported.
  • Compressed blocks are not supported.
  • Encryption is not supported.
  • Backing files are not supported.
  • It's ok if the image contains snapshots. But this program will only provide access to the main image, not the snapshots.
  • Repairing damaged images is not supported.


This program is available under the MIT license.

See also