VDI File Documentation

Summary

A .vdi file is a Virtual Disk Image, the native virtual hard-disk format of Oracle VirtualBox. It stores an entire guest disk — partition table, filesystem and operating system — in one host file, either dynamically allocated or fixed-size. Its MIME type is application/octet-stream. To use it, attach it to a VirtualBox VM and boot, or convert it to .vmdk / .vhd. Being a hard-disk image, it has no meaningful conversion to ISO.

Technical details

Feature	Value
Full name	Virtual Disk Image (VirtualBox)
File extension	`.vdi`
MIME type	`application/octet-stream`
Format type	Binary virtual hard-disk container
Developer	Oracle (originally innotek, then Sun Microsystems)
Introduced	VirtualBox 1.0, 2007
Byte order	Little-endian
Signature (magic)	`7F 10 DA BE` at offset `0x40`
Pre-header text	`<<< Oracle VM VirtualBox Disk Image >>>` (offset 0)
Image types	1 = dynamic, 2 = fixed, 3 = undo/differencing, 4 = diff
Block map offset	typically `0x200` (field `offset_blocks`)
Default block size	1 MiB (`0x100000`)
Unallocated block marker	`0xFFFFFFFF` (−1)
Zero block marker	`0xFFFFFFFE` (−2)
Open standard	Partial (format documented in VirtualBox source)
Allocation modes	Dynamically allocated or fixed-size
Snapshots	Stored as differencing images
Related extensions	`.vmdk`, `.vhd`, `.vhdx`, `.qcow2`, `.raw`, `.ova`
Reference implementation	`VDICore.h` in the VirtualBox source tree
Specification	VirtualBox manual, virtual storage

File signature (magic bytes)

3C 3C 3C 20 … 7F 10 DA BE

A VDI opens with a 64-byte ASCII pre-header text, beginning 3C 3C 3C 20 (<<< ) and usually reading <<< Oracle VM VirtualBox Disk Image >>>. The real binary signature is the four bytes 7F 10 DA BE (the little-endian value 0xBEDA107F) at offset 0x40, immediately followed by the version and header size. Identify a VDI by that signature at 0x40, not by the varying text before it.

What is a VDI file?

VDI stands for Virtual Disk Image, the native virtual hard-disk format of Oracle VirtualBox. The format was created by innotek, the company that built VirtualBox before Sun Microsystems (2008) and then Oracle (2010) acquired it, and it has shipped since VirtualBox 1.0 in 2007. A single .vdi file represents a complete hard disk for a guest operating system: its master boot record or GPT, its partition table, the filesystem inside each partition, the installed OS and every file on it. The host treats that whole disk as one opaque file.

Because it models a hard disk rather than an optical disc, a VDI is not something you “burn” or mount the way you mount an ISO to install software. VirtualBox can equally use VMware’s VMDK, Microsoft’s VHD and VHDX, and plain raw images, and it converts between them, but VDI is the format it writes by default. Everything below describes how VirtualBox lays that disk out on the host, header field by header field. The reference layout lives in the file VDICore.h in the VirtualBox source tree.

The pre-header text and the 0x7F10DABE signature

A VDI begins with a 64-byte ASCII text block at offset 0. It is human-readable and usually reads <<< Oracle VM VirtualBox Disk Image >>>, though the exact wording varies by the tool that created the file (older files and qemu-img write slightly different strings). This text is informational only; a parser must not rely on its content.

The authoritative marker is the 4-byte image signature at offset 0x40: the bytes 7F 10 DA BE, which as a little-endian 32-bit integer is 0xBEDA107F. Every genuine VDI carries this value, and its absence is what VirtualBox reports as an “invalid header”. Directly after it come two 16-bit fields, the major and minor version (offset 0x44), and then a 32-bit header size (offset 0x48) that tells a reader how many bytes of the following main header are valid. That size field is what makes the format extensible: later versions can add fields at the end without breaking a reader that stops at the declared length.

offset  size  field
0x00    64    pre-header text  "<<< Oracle VM VirtualBox Disk Image >>>"
0x40     4    signature        7F 10 DA BE  (LE 0xBEDA107F)
0x44     4    version          uint16 major, uint16 minor  (usually 1.1)
0x48     4    header size      bytes of the main header that follow
0x4C   ...    main header      image type, flags, geometry, sizes, offsets

All multi-byte integers in a VDI are little-endian, which matches the x86 hosts VirtualBox targets and is the opposite of the big-endian byte order used by container formats like MP4.

The main header: image type, geometry and disk size

The main header carries the metadata that turns a flat file into a described disk. Its important fields are the image type, the block sizes, the two internal offsets, the disk geometry and the virtual disk size.

image_type        uint32   1=dynamic  2=fixed  3=undo  4=diff
image_flags       uint32   bit flags (e.g. zero-expand)
description        char[256]
offset_blocks     uint32   file offset of the block-allocation map
offset_data       uint32   file offset where data blocks begin
geometry          cyls, heads, sectors, sector_size  (4 x uint32)
disk_size         uint64   total VIRTUAL capacity in bytes
block_size        uint32   bytes per block (default 0x100000 = 1 MiB)
block_extra       uint32   metadata bytes per block (usually 0)
blocks_in_image   uint32   number of blocks the virtual disk spans
blocks_allocated  uint32   number of blocks actually present in the file
uuid_*            16 bytes  image, last-snapshot, link and parent UUIDs

The image_type field is the first real decision a reader makes. A value of 1 means a dynamically allocated image, 2 a fixed image, and 3 or 4 a differencing image used for snapshots. The disk_size is the size the guest sees, for example 40 GB, while the actual file on the host may be far smaller for a dynamic image. The block_size is the granularity at which VDI allocates storage, 1 MiB (0x100000) by default, so VirtualBox divides the virtual disk into 1 MiB blocks and tracks each one. The header also carries four UUIDs (image, last snapshot, parent link and parent) that tie a differencing chain together; a child image records its parent’s UUID so VirtualBox can refuse to attach a broken chain.

The block allocation map: how a sparse disk works

The block-allocation map is the heart of the format and the reason a dynamic VDI can be much smaller than the disk it represents. It sits at offset_blocks (commonly 0x200) and is a flat array of 32-bit little-endian entries, one per virtual block. Entry n answers a single question: where in the file is the data for the n-th 1 MiB block of the virtual disk?

Two values are reserved sentinels. An entry of 0xFFFFFFFF (interpreted as −1) means the block is unallocated: nothing has ever been written there and no space is reserved for it in the file. An entry of 0xFFFFFFFE (−2) means a zero block: the guest wrote there but the content is all zeroes, which after a discard/TRIM lets VirtualBox drop the physical storage while still returning zeros. Any other value is a real block index; multiplying it by block_size and adding offset_data gives the absolute file position of that block’s 1 MiB of data.

to read virtual byte V of the guest disk:
  block   = V / block_size            // which 1 MiB block
  within  = V % block_size            // offset inside the block
  entry   = block_map[block]          // 32-bit LE lookup
  if entry == 0xFFFFFFFF: return 0    // unallocated  -> reads as zero
  if entry == 0xFFFFFFFE: return 0    // zero block    -> reads as zero
  file_pos = offset_data + entry * block_size + within
  return byte at file_pos

This indirection is what makes a dynamically allocated image grow on demand: the first write into a previously unallocated block appends a fresh 1 MiB block at the end of the data area, updates its map entry to that block’s index, and increments blocks_allocated. A fixed image (type 2) still has a block map, but every entry is filled in up front and the full disk_size is reserved on creation, trading disk space for one less allocation step per first write. Deleting files inside the guest does not shrink the file on its own, which is why VBoxManage modifymedium disk file.vdi --compact exists: after you zero the free space inside the guest, compaction rewrites the map, drops the now-zero blocks, and reclaims host space.

Differencing images and snapshots

A VirtualBox snapshot does not copy the disk. Instead VirtualBox freezes the current VDI as read-only and creates a differencing image (image type 3/4) whose block map is almost entirely 0xFFFFFFFF at first. Every write after the snapshot lands in the differencing child; reads consult the child’s map first and, for any block still marked unallocated there, fall through to the parent image named by the parent UUID. A chain of snapshots is therefore a chain of VDIs, each holding only the blocks that changed since its parent.

This is why the header stores a parent UUID and a parent-modification UUID: when VirtualBox opens a differencing image it checks that the parent it references is the exact image and revision expected, and refuses to attach a chain whose links do not match. Moving a snapshotted VM means moving the whole chain, not a single file, and merging a snapshot (deleting it) walks the child’s map and writes each changed block back into the parent.

VDI versus VMDK, VHD and raw, at the byte level

All of these are virtual hard-disk containers around the same idea, a block map over sparse data, but they differ in header and map layout. VDI uses the 7F 10 DA BE signature and a flat 32-bit block map with 1 MiB granularity. VMDK (VMware) has its own KDMV/COWD sparse-extent headers and can split a disk across many extent files; VHD (Microsoft/Hyper-V) puts a 512-byte footer at the end of the file with the ASCII cookie conectix and, for dynamic disks, a Block Allocation Table near the front. A raw image has no header at all: it is the disk’s sectors written straight through, which is why it is exactly as large as the disk and can be fed to dd or loop-mounted directly.

Because the on-disk structures differ, converting between them is a real rewrite, not a rename. VirtualBox’s bundled tool does it: VBoxManage clonemedium disk in.vdi out.vmdk --format VMDK (or VHD/RAW) reads every allocated block through the VDI map and writes it out in the target layout. The cross-platform qemu-img convert does the same and adds VHDX and qcow2 targets. An OVA/OVF appliance then bundles a VM’s configuration with its disk, though the export step usually stores that disk as VMDK rather than VDI.

Why there is no VDI-to-ISO conversion

A recurring misconception is that a VDI can be turned into an ISO. It cannot, because the two describe different kinds of media. An ISO is an optical-disc image holding an ISO 9660 or UDF filesystem produced for a CD or DVD, read-only and organised around 2048-byte sectors and a fixed volume-descriptor area. A VDI is a read-write hard-disk image whose internal filesystem (NTFS, ext4, APFS, whatever the guest installed) and partition layout have nothing to do with ISO 9660. Tools advertising a “VDI to ISO converter” are either wrong or are really extracting files and re-authoring a new disc image from scratch.

The correct paths depend on the goal. To move the disk to another hypervisor, convert to VMDK, VHD or raw. To pull individual files out without booting, browse the image read-only with 7-Zip, mount it with OSFMount on Windows or guestmount from libguestfs on Linux, and copy what you need. To produce a bootable installer disc you build a fresh ISO from the guest OS’s own installation media, independently of the VDI.

References

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Table of contents