Dissect Hypervisor

3.21 verified Fri May 01 auth: no python

A Dissect module implementing parsers for various hypervisor disk, backup and configuration files (e.g., ESX, Hyper-V, QEMU, VirtualBox). Current version: 3.21. Released as part of the Dissect ecosystem with regular updates.

pip install dissect-hypervisor

Common errors

error ModuleNotFoundError: No module named 'dissect.hypervisor' ↓

cause The package is not installed or the import path is wrong (e.g., using dissect_hypervisor).

fix

Install with pip install dissect-hypervisor and import using from dissect.hypervisor import vhdx

error AttributeError: module 'dissect.hypervisor' has no attribute 'vhdx' ↓

cause The import is incorrect; likely you imported the package but not the submodule.

fix

Use from dissect.hypervisor import vhdx

error dissect.hypervisor.vhdx.VHDX does not support differencing disks ↓

cause The VHDX parser only handles fixed or dynamic disks, not differencing (parent-child) chains.

fix

Merge the differencing disk into a parent first using external tools, or locate the parent VHDX and parse independently.

Warnings

breaking In dissect-hypervisor 3.0+, the import path changed from dissect.hypervisor to a flat module structure. Old imports like `from dissect_hypervisor import esx` will break. ↓

fix Use the new dot notation: `from dissect.hypervisor import esx`.

gotcha The VHDX parser requires the file to be opened in 'rb' mode, and it does not handle compressed or differencing disks automatically. ↓

fix Ensure you open the file with `open(path, 'rb')` and handle parent VHDX files separately for differencing disks.

deprecated The `vhd` module (for legacy VHD files) is deprecated; use `vhdx` for newer formats. ↓

fix Migrate from `from dissect.hypervisor import vhd` to `from dissect.hypervisor import vhdx` for VHDX files. For old VHD, keep using `vhd` but expect removal.

breaking Python 3.9 and below are not supported. Requires Python >= 3.10. ↓

fix Upgrade to Python 3.10 or higher.

Imports

vhdx
wrong
```
from dissect_hypervisor import vhdx
```
correct
```
from dissect.hypervisor import vhdx
```
The package name uses underscores, but imports use dot notation under dissect.hypervisor
esx
```
from dissect.hypervisor import esx
```
qemu
```
from dissect.hypervisor import qemu
```
vbox
```
from dissect.hypervisor import vbox
```

Quickstart

Basic usage to open a VHDX file and list its streams.

from dissect.hypervisor import vhdx

# Open a VHDX file
with open('disk.vhdx', 'rb') as f:
    vhdx_file = vhdx.VHDX(f)
    print('VHDX version:', vhdx_file.header.signature)
    for stream in vhdx_file.streams():
        print('Stream:', stream.type)