A QCOW2 file starts with a header in its first cluster. Version 2 has a 72-byte
header; version 3 adds feature bits and more fields, making at least 104 bytes. This page
follows the specification in the QEMU source, docs/interop/qcow2.rst. All
numbers are big-endian. The file is divided into clusters of 2cluster_bits
bytes, and every table starts on a cluster boundary.
Fields
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
0 | 4 | bytes | magic | 51 46 49 FB: QFI and 0xFB. |
4 | 4 | uint32 | version | 2 or 3. |
8 | 8 | uint64 | backing_file_offset | Where the backing file’s name is in the file, or 0 for none. The name is not zero-terminated and lies in the first cluster, after the header extensions. |
16 | 4 | uint32 | backing_file_size | Length of that name, at most 1,023 bytes. |
20 | 4 | uint32 | cluster_bits | Cluster size as a power of two: at least 9 (512 bytes); QEMU allows up to 21 (2 MiB). 16 (64 KiB) is the default. At least 14 with extended L2 entries. |
24 | 8 | uint64 | size | The virtual disk size in bytes. |
32 | 4 | uint32 | crypt_method | 0 none; 1 AES (AES-256-CBC, deprecated); 2 LUKS. See encryption. |
36 | 4 | uint32 | l1_size | Entries in the active L1 table. |
40 | 8 | uint64 | l1_table_offset | Where the active L1 table is. |
48 | 8 | uint64 | refcount_table_offset | Where the refcount table is. |
56 | 4 | uint32 | refcount_table_clusters | Clusters the refcount table fills. |
60 | 4 | uint32 | nb_snapshots | Number of snapshots. |
64 | 8 | uint64 | snapshots_offset | Where the snapshot table is. |
| Version 2 ends here, at 72 bytes. Version 3 continues: | ||||
72 | 8 | bits | incompatible_features | Features a reader must understand; it must refuse the image if an unknown bit is set. See feature bits. |
80 | 8 | bits | compatible_features | Features a reader may ignore. |
88 | 8 | bits | autoclear_features | Features a writer that does not understand them must clear before writing. |
96 | 4 | uint32 | refcount_order | Refcounts are 2refcount_order bits wide, 0 to 6 (1 to 64 bits). Version 2 is always 4 (16 bits). |
100 | 4 | uint32 | header_length | Length of the header: 72 in version 2; at least 104 and a multiple of 8 in version 3. Header extensions start here. |
104 | 1 | uint8 | compression_type | 0 deflate (raw, no zlib wrapper); 1 zstd. Present only if header_length > 104; must be non-zero exactly when incompatible bit 3 is set. |
105 | 7 | – | Padding | Zeros, up to a multiple of 8. |
A version 3 field is absent when header_length does not reach past its
offset, and an absent field reads as 0. Fields a program does not know must be kept when
it rewrites the header.
Feature bits
| Field | Bit | Name | Meaning |
|---|---|---|---|
| incompatible | 0 | Dirty | The refcounts may be wrong (lazy refcounts were in use and the image was not closed cleanly) and must be repaired before writing. |
| incompatible | 1 | Corrupt | The metadata is damaged; do not write except to repair it. |
| incompatible | 2 | External data file | Guest data is in a separate file, named by a header extension. Its clusters have no refcounts; compressed clusters and internal snapshots are not allowed. |
| incompatible | 3 | Compression type | compression_type is set and not deflate. |
| incompatible | 4 | Extended L2 entries | L2 entries are 128 bits, with subcluster bitmaps; see extended L2. |
| incompatible | 5–63 | Reserved | 0. |
| compatible | 0 | Lazy refcounts | Refcounts may be updated lazily; the dirty bit then marks an image that needs repair. |
| compatible | 1–63 | Reserved | 0. |
| autoclear | 0 | Bitmaps extension | The bitmaps extension is consistent with the image. Cleared by a writer that does not know bitmaps. |
| autoclear | 1 | Raw external data | The external data file is a valid raw image by itself, kept in step with the guest disk. Needs incompatible bit 2. |
| autoclear | 2–63 | Reserved | 0. |
A feature name table extension can give these bits readable names.
Example
The header of a new version 3 image of a 10 GiB disk with 64 KiB clusters, laid out the
way qemu-img create -f qcow2 usually does. The marked bytes are the magic and
version.
00000000 51 46 49 FB 00 00 00 03 00 00 00 00 00 00 00 00 QFI.............
00000010 00 00 00 00 00 00 00 10 00 00 00 02 80 00 00 00 ................
00000020 00 00 00 00 00 00 00 14 00 00 00 00 00 03 00 00 ................
00000030 00 00 00 00 00 01 00 00 00 00 00 01 00 00 00 00 ................
00000040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000060 00 00 00 04 00 00 00 70 00 00 00 00 00 00 00 00 .......p........Reading it: magic and version 3; no backing file; cluster_bits 16, so
64 KiB clusters; size 0x280000000, 10 GiB; no encryption; 20 L1 entries
(each L2 table of 8,192 entries maps 512 MiB) at 0x30000; the refcount
table at 0x10000, one cluster long; no snapshots; no feature bits;
refcount order 4, 16-bit refcounts; header length 112; compression type 0, deflate.
Header extensions start at 112 (0x70).