New version of hv2pve – 1.0.3

In older versions of hv2pve, migration required the virtual machine to be shut down on the Hyper-V side before the process could begin. The result? Every migration involved system downtime, which made the process difficult to use in production environments. The length of the downtime depended on the size of the virtual machine’s disks.

The biggest new feature in the current version

Thanks to the AVHDX Migrate Chain technology (hd2raw) , it is now possible to migrate a virtual machine without shutting it down, significantly reducing service downtime. The entire process takes place online, while the final synchronization of the last snapshot and starting the system on the destination side takes from a few to several dozen seconds in our tests, depending on the current VM workload. The hd2raw tool enables direct synchronization of AVHDX files to the raw format and streams them directly to a disk in the Proxmox environment. This eliminates the need to merge the AVHDX chain beforehand on the Windows side, simplifying the entire migration process and reducing the overall operation time.

What it looks like without our tool

Without using our tool, the migration process from Hyper-V to Proxmox is performed entirely manually. The administrator must first export the VHDX/AVHDX disks and merge the snapshot chain on the Hyper-V side. The disks then need to be converted to a format supported by Proxmox – most commonly raw or qcow2. The next step is to manually create a virtual machine in the Proxmox environment, attach the converted disks, and recreate the hardware configuration (CPU, RAM, network, controllers).

Each of these steps is a separate operation that requires attention and time. As the number of virtual machines being migrated increases, so does the risk of configuration errors. More importantly, the downtime covers the entire time required to copy and convert the data, which in practice can mean several hours of downtime for larger disk volumes.

How it works under the hood (in brief)

The migration process was designed to be predictable, repeatable, and safe – especially when using AVHDX Migrate Chain (AMC). Below is a simplified description of how it works, based on one key assumption: we work with exactly three snapshots.

The migration starts with an inventory on the Hyper-V side. The tool verifies whether the machine meets the migration requirements and whether its state matches the selected mode. In standard mode, the VM must be shut down, while in AMC (AVHDX Migrate Chain) mode it can remain running. The tool also checks whether sufficient storage space is available on Proxmox and whether a machine with the given ID has already been migrated. This helps prevent simple migration errors.

On the Proxmox VE side, a complete virtual machine definition is created, including the disks and their correct attachment to the configuration. The machine is then started and immediately paused, which makes it possible to minimize the subsequent downtime during the actual switchover. This preparation is crucial because the actual import is performed on an already prepared structure. At this stage, the init tag is also assigned, allowing the process to be safely resumed if it is interrupted (e.g. due to network errors).

In AVHDX Migrate Chain (AMC) mode, the actual migration takes place in three snapshot stages:

Snapshot 1 – once it is created, migration of the base VHDX/VHD file begins. The snapshot captures all changes made while the large base disk is being copied, allowing the machine to continue operating normally.

Snapshot 2 – created after the base transfer has completed. It contains the changes generated during the migration of the first layer. The first differencing file is then migrated and merged on both sides – on Hyper-V using the native mechanism and on Proxmox using hd2raw.

Only after the second snapshot has been migrated and merged does the virtual machine shutdown process begin. At this point, the migrator executes the following PowerShell command on the Microsoft Hyper-V host:

Stop-VM -VMName {vmid}

This is the point at which the process enters a short, controlled downtime phase.

Snapshot 3 – created immediately before the VM is shut down and containing the system’s final changes. Once the machine is powered off, the third differencing file is migrated, followed by a merge on both sides – Hyper-V and Proxmox. The machine is then started in the destination environment.

This approach means that most of the data is transferred while the VM is running, with downtime limited to migrating and merging the third snapshot and restarting the system. At the same time, data integrity on the Hyper-V side is preserved, allowing for a quick rollback to the source environment if necessary.

At the end of the process, the machine is assigned the imported tag, clearly confirming that the migration completed successfully and preventing it from being selected again by the hv2pve migrator.

What are the benefits of using AVHDX Migrate Chain?

The biggest benefit of using AVHDX Migrate Chain (AMC) is a dramatic reduction in perceived downtime and better control over migration time.

For example, the difference is clear when migrating a 100 GB virtual machine.

Without AVHDX Migrate Chain – the entire process is performed in the traditional way, meaning that the VM must be shut down while the entire disk is copied and converted. As a result, the downtime spans practically the entire duration of the data transfer:

The migration takes from a few to several dozen minutes, and the downtime covers almost the entire period.

With AVHDX Migrate Chain – most of the data (the base disk and the first two snapshots) is transferred while the machine is running. The VM is shut down only before the third, final snapshot is migrated. The synchronization of the final changes and starting the system in the Proxmox environment usually takes several dozen seconds, depending on the workload:

Although the total operation time may be similar or even longer, the key difference is that downtime is limited exclusively to the final synchronization phase.

The Grafana charts clearly show the shorter service outage when using AVHDX Migrate Chain – the workload is spread over time, and end users experience only a short, controlled restart instead of a long service interruption.

How we tested it

The testing process for the hv2pve migrator was designed to verify not only the correctness of the operation itself, but above all the integrity of the data after migration.

We implemented an additional module in the tool responsible for generating checksum files together with the checksum (sha1sum) recorded in the registry. After the migration was completed, the calculated values were compared with the checksums of files already present in the destination location. This approach allowed us to unambiguously confirm that the data had been transferred completely and had not been corrupted during the transfer or the snapshot synchronization process.

The entire testing process was fully automated using Jenkins. The pipelines ran various migration scenarios – both in standard mode and in AVHDX Migrate Chain (AMC) mode – allowing the tool to be tested repeatedly, consistently, and deterministically. This allowed us to verify both typical migration scenarios and edge cases in a controlled manner, ensuring that hv2pve and hd2raw operate correctly and safely.

What to do if the migration is interrupted

During the migration of a virtual machine to Proxmox VE, situations may occur in which the process does not complete successfully. These issues most commonly concern the state of the machine on the destination side and the snapshots created during the migration.

If the migration is interrupted after all disks have been initialized, the machine on the Proxmox side will receive the init status. This means that the VM structure was created correctly and all disks exist. In this situation, the migration can be safely retried.

However, if the process ends before the disks are fully initialized, the migrator will not assign the init tag and the machine will be marked as corrupted. This status blocks another migration attempt. In practice, this means that the virtual machine and its disks must be manually removed from the Proxmox side, after which the migration needs to be started again from scratch.

A separate case occurs when snapshots are created during migration and the process is interrupted after they have already been created. In such a scenario, the snapshots remain in the environment and prevent another migration attempt – the VM receives the snapshot status. At the moment, removing or “cleaning up” these snapshots remains the user’s responsibility. Migration can only be restarted after the snapshots have been manually removed.

Next steps

Development of the migrator is currently focused on improving its resilience to errors. The key goal is to reduce situations in which the administrator has to manually clean up the environment after an interrupted migration.

We plan to improve exception handling and introduce mechanisms for automatically cleaning up snapshots on the Microsoft Hyper-V side – both during migration (if the state of the process allows it) and when restarting a migration. This will allow the source environment to remain in a consistent state even after an unsuccessful import attempt.

At the same time, we are working on the ability to resume an import after an error without having to manually remove the machine on the Proxmox VE side. This will be complemented by automatic cleanup of the VM and storage resources after a failed import.

The roadmap also includes:

• refactoring the project and separation of a dedicated Service Layer
• dynamic number of checkpoints during AMC migration
• automatic selection of the appropriate datastore for the VM in Proxmox
• migration of block devices and iSCSI
• migration from a Microsoft Hyper-V cluster to a PVE cluster with automatic virtual machine placement
• support for migrating multiple machines in parallel
• disk transfer via NFS and SSH
• generic EFI support
• web GUI for migration management (progress monitoring, configuration, and error handling)

Tutorial: How to migrate a VM

hv2pve repository

The first step is to prepare the environment on the Hyper-V side and the source virtual machine. Run the appropriate script from the prep_script directory to prepare the VM for migration. If you plan to use AVHDX Migrate Chain (AMC), set the HYPERV_CREATE_CHECKPOINT variable during environment configuration (see the env.json file section for details).

Next, select the virtual machine import mode. By default, the program will report skip due to CheckVMState – the VM must be shut down. To use AVHDX Migrate Chain mode, you need to enable the nbd module on the Proxmox side and download the separate hd2raw binary, which enables synchronization of AVHDX files to the raw format.

1. Create a virtual environment (venv): python3 -m venv ./venv
2. Activate the virtual environment: source ./venv/bin/activate
3. Install the dependencies: pip install -r req.txt
4. Configure the Hyper-V/Proxmox connection in env.json. To use AVHDX Migrate Chain mode, set HYPERV_CREATE_CHECKPOINT to true: { "HYPERV_IP": "a.b.c.d", "HYPERV_USER": "administrator", "HYPERV_PASS": "changeme", "HYPERV_CREATE_CHECKPOINT": true, ... }
5. Run the initial verification: make dryrun
6. Start the migration: make run
7. Run the migration in debug mode (optional): make debug