Format:QCOW2
| On this wiki | Facts · Code · Notes · Topics |
|---|
QEMU's copy-on-write disk image (magic "QFI\xfb", versions 2 and 3): a big-endian header with cluster_bits, a two-level L1/L2 table mapping guest clusters, a refcount table, optional backing file and snapshots, and feature bit fields in version 3.
Identification
First four bytes 51 46 49 FB ("QFI" 0xfb, QCOW_MAGIC), followed by a big-endian version. QEMU accepts only versions 2 and 3 (qcow2.c: header.version < 2 || header.version > 3 is an error). All fields are big endian.
Header (QCowHeader, qemu block/qcow2.h)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | magic |
| 4 | 4 | version (2 or 3) |
| 8 | 8 | backing_file_offset |
| 16 | 4 | backing_file_size |
| 20 | 4 | cluster_bits (cluster size = 1 << cluster_bits) |
| 24 | 8 | size (virtual size in bytes) |
| 32 | 4 | crypt_method (0 none, 1 AES, 2 LUKS) |
| 36 | 4 | l1_size (entries) |
| 40 | 8 | l1_table_offset |
| 48 | 8 | refcount_table_offset |
| 56 | 4 | refcount_table_clusters |
| 60 | 4 | nb_snapshots |
| 64 | 8 | snapshots_offset |
| 72 | 8 | incompatible_features (v3) |
| 80 | 8 | compatible_features (v3) |
| 88 | 8 | autoclear_features (v3) |
| 96 | 4 | refcount_order (refcount width = 1 << order bits; QEMU rejects > 6) |
| 100 | 4 | header_length (v3) |
| 104 | 1 | compression_type (v3 additional field) |
Version 2 headers end at offset 72. Cluster size limits: MIN_CLUSTER_BITS 9 (512 B) to MAX_CLUSTER_BITS 21 (2 MiB); default 64 KiB.
Mapping
L1 table (8-byte entries) points to L2 tables (one cluster each, 8-byte entries, or 16 bytes with extended L2). Entry flags: bit 63 QCOW_OFLAG_COPIED (refcount is exactly 1), bit 62 QCOW_OFLAG_COMPRESSED, bit 0 QCOW_OFLAG_ZERO (reads as zeros). Offset mask for L1/L2 standard entries 0x00fffffffffffe00. Compressed clusters carry a different descriptor (offset and sector count packed in the low bits). Refcounts live in blocks addressed through the refcount table.
Feature bits (version 3)
Incompatible: bit 0 dirty, bit 1 corrupt, bit 2 external data file, bit 3 compression type, bit 4 extended L2 (subclusters). Compatible: bit 0 lazy refcounts. Autoclear: bit 0 bitmaps, bit 1 raw external data file. A reader must refuse an image with an unknown incompatible bit.
Header extensions
After the header, 4-byte magic + 4-byte length + padded data entries until magic 0: 0xE2792ACA backing file format, 0x6803F857 feature name table, 0x0537BE77 full-disk encryption header pointer (LUKS, see Format:LUKS), 0x23852875 bitmaps, 0x44415441 external data file name.
Analyst notes
- To read a qcow2 without QEMU: parse the header, walk L1 -> L2, treat unallocated entries as reading from the backing file (or zeros), and decompress flagged clusters (Unverified: raw deflate is the default compression type).
- Unverified: snapshots share clusters; internal snapshot L1 tables are listed at snapshots_offset.
Code & repositories
- qemu
block/qcow2.h,block/qcow2.c(GPL-2.0). - https://github.com/qemu/qemu @
a19f59a72d96056d9a8f48cf6c77f5787491e414· license: GPL-2.0-only (declared by the contributor; GitHub's detector did not recognize COPYING)
block/qcow2.h, vpc.c, vhdx.h/.c, vmdk.c, vdi.c: on-disk structures of the virtual disk formats (COPYING is GPL-2.0; individual files carry GPL/MIT headers)
Tested on: source read, not run: source read only · checked 2026-10-19; last activity 2026-10-17