4 releases (2 breaking)

0.3.1 May 9, 2023
0.3.0 May 9, 2023
0.2.0 Oct 6, 2021
0.1.0 Aug 31, 2021

#1220 in Filesystem

MIT and LGPL-3.0-or-later

1.5K SLoC


docs.rs/qcow crates.io 100% documented MIT Licensed

A Rust library for working with qcow images.


// open qcow
let qcow = qcow::open(PATH).unwrap();

// print out list of snapshots in the qcow
for snapshot in qcow.snapshots() {
        "Snapshot {:?}: {:?} (size = {})",

// create a reader for accessing the virtual hard disk
let mut file = BufReader::new(File::open(PATH)?);
let qcow2 = qcow.unwrap_qcow2();
let mut reader = qcow2.reader(&mut file);

// read the first 10 bytes of the virtual hard disk
let mut buf = [0; 10];
reader.read_exact(&mut buf)?;

Library Features

  • Parse qcow files
  • Full qcow version 1 support
    • Support for parsing the header and some associated data
  • Full qcow version 2-3 support
    • Header parsing, including extra version 3 header data
    • Header extension parsing, allowing you to use addition data they provide
    • Lookup table (L1 and L2) parsing, only loading L2 tables on demand
    • Snapshot parsing, including snapshot L1 lookup tables
    • Support for reading the contents of the virtual disk
      • Includes compression support (for both zlib and zstd)
      • Cluster lookup caching, backtracking on cache miss
      • Allows arbitrary seeking within the guest
    • Supports 'recursive' qcows which have another qcow on-disk as a backing file store

Command Line Interface

Also present is a cli for interfacing with qcows.

qcow-cli 0.2.0
A utility for querying information about qcow files

    qcow <qcow> <SUBCOMMAND>

    -h, --help       Prints help information
    -V, --version    Prints version information


    get-file      Output a file within the qcow to stdout
    help          Prints this message or the help of the given subcommand(s)
    info          Output info about the given qcow
    partitions    Display a list of partitions in the qcow image
    tree          Display a tree listing of the contents of the qcow


cargo install qcow-cli


Listing info about the qcow:

info command

Viewing the file tree:

tree command

Viewing the image partitions:

partitions command

Extracting or viewing a file using get-file:

get-file command


~550K SLoC