How to Migrate Virtual Machines from Hyper-V to Proxmox – A Simple Step-by-Step Guide

Migrating virtual machines between different virtualization environments may seem complicated. Fortunately, with the prepared script hv2pve, the entire process of transferring machines from Hyper-V to Proxmox becomes much simpler. In this post, I will show you how to prepare the environment and carry out the migration step by step.

1. Prerequisites – before you start

First, download the files from our repository https://github.com/blackrack/hv2pve. You need to adjust the configuration file env.json, where you define all the necessary parameters. Here are example settings that you need to change:

"HYPERV_IP": "192.168.100.129",
"HYPERV_USER": "administrator",
"HYPERV_PASS": "YourPassword",
"HYPER_VM_LIST": [
  "UUID_machine_1",
  "UUID_machine_2"
],
"HYPERV_AUTO_SHAREDISK": true,
"HYPERV_SHAREDISK_MAPPING": [
  {
    "C:/VMDisks": "VMDisks",
    "PROXMOX_STORAGE": "data"
  },
  {
    "E:/VMDisksSSD": "VMDisksSSD",
    "PROXMOX_STORAGE": "space"
  }
],
"PROXMOX_IP": "192.168.100.252",
"PROXMOX_USER": "root",
"PROXMOX_PASS": "YourPassword",
"PROXMOX_MOUNTPATH": "/root/tmp",
"PROXMOX_IMPORTPATH": "/root/import",
"PROXMOX_STORAGE": "data",
"PROXMOX_SWITCH_DEFAULT": "vmbr0",
"PROXMOX_SWITCH_MAPPING": {
  "UUID_switch": "vmbr1"
},
"PROXMOX_NETWORK_TYPE": "e1000",
"PROXMOX_START_AFTER": true,
"PROXMOX_IMPORT_ONCE": false

💡 Note: You can view the UUIDs of machines and switches from Hyper-V in the Hyper-V Manager or via a script.

2. Preparing systems for migration

In the prep_script directory, you will find three helper scripts that need to be executed:

• prep_hyper-v.ps – run it on the Hyper-V machine to prepare the environment.
• debian.sh – run it on virtual machines with Debian or derivatives.
• rocky.sh – run it on machines from the RHEL family (e.g., Rocky Linux).

Additionally:
➡️ On Windows machines, in Hyper-V Manager, add the entry os:windows in the “Notes” tab.

3. Preparing the environment on the Proxmox machine

1. Create a virtual Python environment:

   python3 -m venv ./venv
   

2. Activate the environment:

   source ./venv/bin/activate
   

3. Install the required libraries:

   pip install -r req.txt
   

4. Complete the env.json file according to the previous description.
5. Perform a pre-migration verification:

   make dryrun
   

4. Starting the migration

If everything is ready, simply start the migration:

• Standard migration:

  make run
  

• Debug mode (when you want to trace the entire process step by step):

  make debug
  

Where to find the necessary data for env.json?

1. UUID of virtual machines (HYPER_VM_LIST)

You can find the UUID of each machine in PowerShell on the Hyper-V host. Type:

Get-VM | Select-Object Name, Id

You will see a list of machines and their identifiers. Example:

Copy these identifiers to the HYPER_VM_LIST section.

 2. UUID of Hyper-V switches (PROXMOX_SWITCH_MAPPING)

To check the identifiers of the switches, use:

Get-VMSwitch | Select-Object Name, Id

Example:

In PROXMOX_SWITCH_MAPPING, you can map these switches to the appropriate bridges in Proxmox, e.g., vmbr1, vmbr2.

3. How to check available bridges in Proxmox?

Log in to Proxmox and check the available network bridges in the console:

cat /etc/network/interfaces

Look for entries like:

auto vmbr0
iface vmbr0 inet static
    ...

These names (vmbr0, vmbr1, etc.) are what you will use in the configuration.

4. How does disk mapping work (HYPERV_SHAREDISK_MAPPING)?

If you have several physical or logical disk locations on Hyper-V (e.g., C:VMDisks and E:VMDisksSSD), you can assign each to a specific storage in Proxmox (e.g., data, space).

This allows, for example, to migrate SSD disks to fast storage in Proxmox.

Example:

{
  "C:/VMDisks": "VMDisks",
  "PROXMOX_STORAGE": "data"
}

This means: disks from C:VMDisks should go to the data storage in Proxmox.

5. What are PROXMOX_IMPORTPATH and PROXMOX_MOUNTPATH?

• PROXMOX_MOUNTPATH: temporary location where Proxmox will mount the network share from Hyper-V.
• PROXMOX_IMPORTPATH: directory where the converted .qcow2 images go before final import.

Useful tips

• Before the actual run, always do a make dryrun. This will check if everything is configured correctly.
• If something goes wrong, use make debug — you will see detailed logs.
• Windows machines require special marking: add the value os:windows in the “Notes” field so that the script correctly recognizes the system type.

Summary

Migrating machines from Hyper-V to Proxmox doesn’t have to be difficult. With automation and a well-prepared script hv2pve, you can carry out the entire process smoothly and without unnecessary stress. If you take care of the correct configuration and preparation of the environments, everything should go smoothly!

Do you have questions or want to share your migration experiences? Contact us!