Migration from ESXi and XCP-ng
ProxCenter provides automated migration pipelines to move virtual machines from VMware ESXi and XCP-ng (Xen) to Proxmox VE. This is designed for organizations transitioning away from VMware or consolidating heterogeneous virtualization environments onto Proxmox.
Overview
The migration feature handles the entire workflow: connecting to the source hypervisor, downloading VM disks, converting disk formats, importing into Proxmox, and configuring the resulting VM. All progress is tracked in real time through the ProxCenter interface.
Two migration pipelines are available:
- ESXi to Proxmox -- Migrates VMs from VMware ESXi hosts, including VMs on vSAN datastores
- XCP-ng to Proxmox -- Migrates VMs from XCP-ng / Xen hosts via the XAPI interface
Migration Modes
ProxCenter offers two migration modes, selectable in the Migrate to Proxmox VE dialog.
Offline migration (cold). The source VM is powered off and its disks are copied in full, converted with qemu-img, then imported into Proxmox. This works for any source (ESXi, vCenter, XCP-ng). The open-source tooling the conversion needs on the Proxmox node (nbdkit, libnbd-bin) is installed automatically during the migration if it is missing, so the offline path needs no manual node preparation.
Warm migration (CBT). The source VMware VM stays online while ProxCenter copies its disks using VMware Changed Block Tracking. A short cutover then performs a clean guest shutdown and a final delta sync, so there is no data loss on large or busy disks. Warm migration needs a block-storage target (LVM, ZFS or Ceph) and the VMware VDDK runtime installed on the Proxmox node.
Unlike offline migration, the warm path cannot install its runtime automatically, and ProxCenter has never installed it for you. The VMware VDDK is a proprietary Broadcom SDK that cannot be redistributed, and the nbdkit VDDK plugin ships in the Debian non-free repository, which a stock Proxmox node does not enable. You must prepare each target node once, as described in Warm migration node setup, before a warm migration can start. ProxCenter runs a readiness check in the dialog and blocks the migration until the node is ready.
Prerequisites
- Source hypervisor credentials with permission to read VM metadata and export disks. See Source hypervisor privileges for the exact vCenter and ESXi role to grant.
- Target Proxmox API credentials with permission to create VMs and write to the target storage.
- SSH access to the target Proxmox node for import and conversion operations.
- Enough temporary storage and network bandwidth for full disk transfers.
- VirtIO drivers available for Windows guests when using VirtIO disk or network devices.
- For warm migration, the target Proxmox node also needs the VMware VDDK runtime installed once. See Warm migration node setup.
For large migrations, validate one representative VM before scheduling a bulk migration window.
Source hypervisor privileges
ProxCenter never modifies the source VM. It authenticates to the source hypervisor, reads the VM configuration and inventory, and exports the disks. The account you use therefore needs read access plus the right to export a VM. The exact requirements differ slightly between a standalone ESXi host and a vCenter.
vCenter
vCenter migrations use the canonical NFC transport: ProxCenter asks vCenter to open an export lease (the ExportVm and ExportSnapshot API) and streams the disks over it. This requires the vApp > Export privilege. When it is missing, vCenter rejects the export with SOAP error 500: Permission to perform this operation was denied, and the migration stops at the "Initiating NFC export lease" step.
The simplest least-privilege setup is to clone the built-in Read-only role, add the privileges below, then assign the resulting role to your migration user at the datacenter level, propagated to child objects so it covers both the VMs and their datastores.
| Privilege | Required for |
|---|---|
| vApp > Export | Opening the NFC export lease. Mandatory, this is the privilege that triggers the SOAP 500 above when absent. |
| Virtual machine > Provisioning > Allow read-only disk access | Reading the disk data over the lease |
| Virtual machine > Provisioning > Allow virtual machine download | Downloading the disk and descriptor files |
| Virtual machine > Interaction > Power Off | Offline migration powers the source VM off before export |
| Virtual machine > Snapshot management > Create snapshot | Warm migration creates a transfer snapshot |
| Virtual machine > Snapshot management > Remove snapshot | Warm migration removes the transfer snapshot after cutover |
| Read-only (built-in role, used as the base) | Authentication and reading VM configuration and inventory |
The built-in Administrator role already includes all of these, so an administrator account works without any extra configuration. The table above is only needed when you want a dedicated, least-privilege migration account.
Standalone ESXi
A direct ESXi migration downloads the disks over the host datastore API rather than through an NFC lease. A user in the host Administrator role works out of the box. For a restricted account, grant read access to the VM and its datastore, plus Virtual machine > Interaction > Power Off for offline migration.
Pipeline Stages
Each migration goes through these sequential stages:
1. Download
The VM disk is downloaded from the source hypervisor. For ESXi, this uses the VMware VDDK / HTTP file access. For XCP-ng, the disk is exported via the XAPI export interface.
2. Convert
The downloaded disk is converted to a Proxmox-compatible format using qemu-img convert. VMDK files (ESXi) and VHD files (XCP-ng) are converted to qcow2 or raw format depending on the target storage type.
3. Import
The converted disk is imported into Proxmox using qm disk import, which uploads the disk to the selected target storage and associates it with a new or existing VM.
4. Configure
The imported VM is configured with the original settings: CPU count, memory, network interfaces, and boot order. The boot disk is set automatically so the VM is ready to start.
For EFI-based VMs, ProxCenter automatically handles the EFI disk allocation. The data disk may be assigned to disk-1 instead of disk-0 since disk-0 is used for the EFI disk.
Warm Migration Node Setup
Before the first warm migration to a Proxmox node, install the VDDK runtime on that node. The dialog probes the selected node and shows "Target node is not ready for warm migration" with the list of missing components until all of them are present. This is a one-time setup per node.
The warm path needs four components on the Proxmox node:
| Component | Source | Notes |
|---|---|---|
nbdkit | Debian main | Available on a stock Proxmox node. |
nbd-client | Debian main | Available on a stock Proxmox node. |
nbdkit-plugin-vddk | Debian contrib / non-free | Not enabled by default on Proxmox. Enable the repositories first. |
Broadcom VDDK (libvixDiskLib.so*) | Broadcom download | Proprietary SDK. Requires a Broadcom account and acceptance of the license. |
1. Install nbdkit and nbd-client
These are in the standard Debian repositories:
apt update
apt install nbdkit nbd-client
2. Install the nbdkit VDDK plugin
The plugin lives in Debian non-free. Enable contrib and non-free in the node's apt sources, then install it:
# Proxmox VE 8 (Debian 12): add contrib and non-free to the apt sources, e.g.
# deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
apt update
apt install nbdkit-plugin-vddk
3. Install the Broadcom VDDK
The VMware Virtual Disk Development Kit (VDDK) is a proprietary Broadcom SDK and is not available from any package repository. Download it from the Broadcom developer portal (a Broadcom account and acceptance of the license are required):
https://developer.broadcom.com/sdks/vmware-virtual-disk-development-kit-vddk/latest/
Install the runtime libraries under /usr/lib/vmware-vix-disklib so that libvixDiskLib.so* ends up in /usr/lib/vmware-vix-disklib/lib64/:
# After downloading VMware-vix-disklib-<version>.x86_64.tar.gz from Broadcom:
mkdir -p /usr/lib/vmware-vix-disklib
tar xzf VMware-vix-disklib-*.tar.gz -C /usr/lib/vmware-vix-disklib --strip-components=1
ldconfig
The nbdkit version shipped with Proxmox loads the libvixDiskLib.so.8 library name. If you installed VDDK 9.x, create the matching symlink (or install VDDK 8.0.x instead):
cd /usr/lib/vmware-vix-disklib/lib64
ln -sf libvixDiskLib.so.9 libvixDiskLib.so.8
ldconfig
4. Prevent LVM from auto-activating guest volume groups
Required when migrating Linux guests that use LVM (most enterprise Linux templates). During a warm migration the guest disk is attached to the Proxmox node as an NBD device. If the node's LVM scans it, it auto-activates the guest's volume group on the host and pins the NBD device: the migration can no longer release it afterwards, nbd-client -d and rmmod nbd both fail, and the device stays wedged until the node is rebooted.
Tell LVM to ignore NBD devices on the target node. Edit /etc/lvm/lvm.conf and, in the devices { } section, set:
global_filter = [ "r|/dev/nbd.*|", "a|.*|" ]
Then reboot the node. The reboot both applies the filter and clears any device that is already wedged. If you prefer not to reboot, run vgchange -an <guest-vg> for the activated guest volume group and pvscan --cache after editing the file.
Proxmox's own LVM and LVM-Thin storage lives on physical disks, never on /dev/nbd*, and warm migration reads the guest disk as a raw device rather than through LVM. The filter only stops LVM from touching the transient NBD devices used during migration.
5. Reselect the node
Back in the Migrate to Proxmox VE dialog, reselect the target node. The readiness check runs again and, once every component is detected, shows "Target node is ready for warm migration" and enables the migration button.
ProxCenter confirms nbdkit and nbd-client are on PATH, that nbdkit-vddk-plugin.so exists under /usr/lib or /usr/lib64, and that libvixDiskLib.so* exists under the VDDK library directory (/usr/lib/vmware-vix-disklib/lib64 by default).
Starting a Migration
- Navigate to Automation > Migration
- Select the source type (ESXi or XCP-ng)
- Enter the source hypervisor connection details (host, credentials)
- ProxCenter connects and lists all VMs available on the source
- Select one or more VMs to migrate
- Choose the target Proxmox connection, node, and storage
- Configure options (VM name, VMID, network bridge, etc.)
- Start the migration
Bulk Migration
You can select multiple VMs and migrate them in a single batch. Migrations run sequentially to avoid overloading the network and storage. The Task Center shows progress for each VM individually.
For large migrations, consider running them during off-peak hours. Each VM migration involves downloading the full disk image, which can take significant time depending on disk size and network bandwidth.
Cross-Cluster Migration
ProxCenter tracks progress for offline cross-cluster VM moves between Proxmox environments. Progress updates are reported in the UI so operators can distinguish long-running disk transfer from stalled operations.
When migrating to another cluster, you can target a specific VMID on the destination. VLAN tags on migrated network interfaces are preserved when the target bridge supports the same network design.
vSAN Support
ProxCenter supports migrating VMs from ESXi hosts that use VMware vSAN storage. The migration pipeline handles the vSAN object retrieval transparently -- no special configuration is needed beyond providing valid ESXi credentials with read access to the datastore.
Storage Considerations
The target storage type affects the import behavior:
| Storage Type | Disk Format | Volume Naming |
|---|---|---|
| Local (directory) | qcow2 | local:VMID/vm-VMID-disk-N.qcow2 |
| NFS | qcow2 | nfs-storage:VMID/vm-VMID-disk-N.qcow2 |
| LVM / LVM-Thin | raw | lvm-thin:vm-VMID-disk-N |
| ZFS | raw | zfs-pool:vm-VMID-disk-N |
| Ceph RBD | raw | ceph:vm-VMID-disk-N |
Troubleshooting
Migration stuck at "Import" stage
The qm disk import command can take a long time for large disks. Check the Task Center for the detailed log output.
VM does not boot after migration Verify the boot order is set correctly. For EFI VMs, ensure the OVMF BIOS is selected in the VM hardware settings. You may need to change the disk controller from VirtIO to IDE/SATA if the guest OS does not have VirtIO drivers.
Network not working after migration The VM network interface model may need to change. VMware uses VMXNET3, which does not exist in Proxmox. ProxCenter defaults to VirtIO, but some guest OSes may need driver installation.
"Target node is not ready for warm migration"
The selected node is missing one or more warm-migration components (nbdkit, nbd-client, nbdkit-plugin-vddk, or the Broadcom VDDK). Prepare the node as described in Warm migration node setup, then reselect the node in the dialog. This requirement applies to warm migration only: offline migration installs its open-source tooling automatically and does not need the VDDK.
Warm migration fails with "nbd: nbd0 already in use" or a wedged NBD device
A previous warm migration of a Linux/LVM guest left an NBD device pinned on the target node: the host auto-activated the guest's LVM volume group on it, so nbd-client -d returns success without freeing it and rmmod nbd reports the module is in use (lsof shows nothing, because the holders are LVM / device-mapper, not open files). Prevent this by setting the LVM global_filter described in step 4 of Warm migration node setup; reboot the node to clear a device that is already wedged.
Migration requires SSH access to the target Proxmox node for disk import operations. Make sure the SSH connection is configured in Settings > Connections.
The Migration feature is available in the Enterprise edition.
Permissions
| Permission | Description |
|---|---|
vm.create | Required to create the target VM on Proxmox |
storage.write | Required to import disks to the target storage |
migration.manage | Required to initiate and manage migration jobs |