Skip to main content

VMCraft: Why We Built a Pure Python VM Engine (And Ditched libguestfs)

· 5 min read
HyperSDK Team
HyperSDK Team
Core Team

When we started building hyper2kvm, the VM conversion engine that powers HyperSDK migrations, we assumed we would use libguestfs for disk image manipulation. It is the standard tool, backed by Red Hat, with a mature API and wide Linux distribution support. Six months in, we replaced it entirely with VMCraft -- a pure Python VM manipulation engine that reads and writes disk images directly without booting an appliance. This post explains why, and what we gained.

The libguestfs Problem​

libguestfs works by booting a lightweight virtual machine (the "appliance") every time you need to access a disk image. This appliance contains a Linux kernel, a minimal userspace, and filesystem drivers. Your application communicates with the appliance over a socket, sending commands to read files, write data, or modify configurations inside the disk image.

This architecture has three fundamental problems that became deal-breakers for hyper2kvm.

Startup latency. Every time you open a disk image, libguestfs boots the appliance. This takes 15-30 seconds depending on hardware. For a migration pipeline that processes hundreds of VMs, this adds hours of idle waiting. We measured 22 seconds average appliance boot time on our reference hardware -- multiplied by 200 VMs, that is 73 minutes spent doing nothing but waiting for appliances to start.

Memory consumption. The appliance requires 512 MB or more of memory per instance. Running parallel conversions -- essential for large-scale migrations -- means allocating gigabytes of memory just for the disk manipulation layer, before you account for the actual conversion work.

Deployment complexity. The appliance depends on supermin, a specific kernel version, and /dev/kvm access on the host. In containerized deployments, this means running privileged containers with device access -- a non-starter for many enterprise security policies. In air-gapped environments, pre-staging the appliance kernel and initrd adds another layer of complexity to an already constrained deployment process.

The VMCraft Architecture​

VMCraft replaces the appliance with direct block device access. The architecture is simple: Python application code calls VMCraft APIs, which use qemu-nbd to expose the disk image as a block device, then parse filesystem structures (ext4, NTFS, XFS, FAT32) directly in Python.

This sounds like it should be slower -- Python parsing filesystem metadata instead of a native kernel driver. In practice, it is dramatically faster for the operations that matter in a migration pipeline, because there is no 22-second appliance boot. VMCraft opens a disk image in under one second.

For bulk operations (read a registry key, inject a driver file, modify fstab), the per-operation overhead of Python parsing versus kernel drivers is negligible compared to the I/O time. The bottleneck is always disk I/O, not CPU time spent parsing superblock structures.

480+ API Functions​

VMCraft provides 480+ functions organized across six categories that cover every operation needed for VM migration.

Disk image operations handle format support (QCOW2, VMDK, VHD, VHDX, RAW), partition table parsing (MBR and GPT), and image manipulation (resize, compact, convert, snapshot).

Filesystem access provides read/write access to ext2/3/4, XFS, NTFS, and FAT32 filesystems. You can list directories, copy files in and out, modify permissions, and create or delete entries -- all without mounting the filesystem on the host.

Windows-specific operations include full Windows registry hive read/write, VirtIO driver injection into the driver store, BCD (Boot Configuration Data) editing for bootloader repair, service configuration, and Sysprep/unattend.xml generation.

Linux-specific operations cover fstab modification, GRUB and systemd-boot configuration, kernel module injection, network configuration across NetworkManager and systemd-networkd, and cloud-init seed injection.

Guest OS detection automatically identifies the operating system type, version, installed applications, hardware drivers, network configuration, and boot method (BIOS vs. UEFI) -- critical metadata for migration planning.

Security and integrity functions provide SHA-256 checksum generation and verification, disk image encryption, secure wipe of free space, and certificate injection.

Performance Numbers​

We benchmarked VMCraft against libguestfs across the operations most common in our migration pipeline.

Opening a disk image and reading a single file: libguestfs averaged 23.4 seconds (dominated by appliance boot), VMCraft averaged 0.8 seconds -- a 29x improvement. Injecting VirtIO drivers into a Windows VM: libguestfs took 31.2 seconds, VMCraft took 4.6 seconds -- 6.8x faster. Modifying fstab and GRUB configuration in a Linux VM: libguestfs took 24.1 seconds, VMCraft took 3.2 seconds -- 7.5x faster.

For batch processing of 200 VMs (the common enterprise migration scenario), the cumulative time savings exceeded 90 minutes. More importantly, VMCraft's lower memory footprint (under 50 MB versus 512 MB+) allows running more parallel conversions on the same hardware, further reducing total migration time.

Container-Friendly by Design​

VMCraft runs inside standard containers without /dev/kvm, without privileged mode, and without device access. The only requirement is qemu-nbd, which operates as a regular userspace process. This makes VMCraft compatible with Kubernetes pods, rootless Podman containers, and CI/CD pipeline runners -- environments where libguestfs appliance boot is typically impossible or requires security exceptions.

For organizations evaluating hyper2kvm for VM migration, VMCraft's container-friendly architecture means the conversion pipeline can run anywhere your container orchestrator runs, without special host configuration. Schedule a demo to see VMCraft's 480+ APIs in action.