Microsoft's Virtual Hard Disk (VHD) Format

Usage no npm install needed!

<script type="module">
  import vhd from 'https://cdn.skypack.dev/vhd';


VHD - Virtual Hard Disk

npm npm npm downloads build status

VHD (Virtual Hard Disk) is a file format which represents a virtual hard disk drive (HDD). It may contain what is found on a physical HDD, such as disk partitions and a file system, which in turn can contain files and folders. It is typically used as the hard disk of a virtual machine. The format was created by Connectix for Connectix Virtual PC product, which was later acquired by Microsoft in 2003, for what is now known as Microsoft Virtual PC. Since June 2005, Microsoft has made the VHD Image Format Specification available to third parties under the Microsoft Open Specification Promise.

From Wikipedia's VHD article

Install via npm

$ npm install --save vhd



  • Fixed — The VHD image file is pre-allocated on the backing store for the maximum size requested.
  • Expandable — The VHD image file uses only as much space on the backing store as needed to store the actual data the virtual disk currently contains. Note: The maximum size of a dynamic virtual disk is 2,040 GB.
  • Differencing — A parent virtual disk is used as the basis of this type, with any subsequent writes written to the virtual disk as differences to the new differencing VHD image file, and the parent VHD image file is not modified. Note: The maximum size of a dynamic virtual disk is 2,040 GB.

For more information, see MSDN


All virtual disk types have a minimum size of 3 MB.

The VHD format has a built-in limitation of just under 2 TiB (2040 GiB) for the size of any dynamic or differencing VHDs. This is due to a sector offset table that only allows for the maximum of a 32-bit quantity - Which fits our JavaScript environment perfectly, since we can't work with 64 bit integers natively.

Memory Requirements

For a maximum size dynamic or differencing VHD, the maximum Block Allocation Table size amounts to just under 4MB with the default sector size of 2MB (4096 512-byte blocks per sector)

MAX_BAT_SIZE = ( tableEntries = ( diskSize / sectorSize )) * VHD.TABLE_ENTRY_SIZE


var VHD = require( 'vhd' )

Fixed size VHD

var fixed = new VHD.Fixed( './path/to/image.vhd' )
fixed.open( function( error ) {
  if( error ) {
    // Obviously, something went wrong...
  } else {
    // Ready to read/write to/from image
fixed.read( offset, length, function( error, bytesRead, buffer ) {
  // ...
fixed.write( buffer, offset, function( error, bytesWritten, buffer ) {
  // ...
fixed.close( function( error ) {
  // ...



  • Write tests
  • Add integration tests (with node-disk etc.)
  • Flesh out docs
    • Generate API docs
    • Complete VHD spec doc
  • Add runnable examples
  • Add PR & Issue templates (?)

Dynamic Images

  • Impl BlockDevice API
    • Impl partitions
  • Impl cross-sector reads
  • Impl writes

Fixed Images

  • Impl BlockDevice API
    • Impl partitions