The native ESXi import wizard · Proxmox VE

Earlier lessons in this part cover migration from VMware the general way: export the disks, convert them, build a guest around them, fix the drivers. That path still matters and it still works.

Proxmox VE also ships a shorter one. There is a storage plugin whose type is esxi: point it at an ESXi host, and its virtual machines appear in the Proxmox resource tree as importable objects. No intermediate export, no scratch space for a .ova, no conversion step you run yourself.

It is the right first choice for most VMware estates, and this lesson is about knowing before you start whether yours is one of them.

Adding the storage

Configuration changeconnect to an ESXi host— Changes cluster configuration. Creates a read-only view of the ESXi host's virtual machines as an importable storage. The credentials are an ESXi administrative account and are stored by PVE; use a dedicated account for the migration and remove it afterwards.

pvesm add esxi esxi-src \
--server 192.0.2.80 \
--username migration@example.com \
--password REPLACE_ME

pvesm status --storage esxi-src

The wiki documents the same operation in the GUI as Datacenter → Storage → Add → ESXi, with server, username and password, plus a skip-cert-verification option for hosts using a self-signed certificate.

Read-only / Safesee what the ESXi host is offering— Read-only. Lists the importable objects the plugin has discovered. Each entry is a virtual machine on the ESXi host, not a copy of one — nothing has been transferred yet.

pvesm list esxi-src

pvesm status --content import

Read-only / Safe

$ pvesm list esxi-src

Volid                                          Format  Type    Size          VMID
esxi-src:ha-datacenter/APP-WEB-01/APP-WEB-01.vmx  vmx   import  85899345920      0
esxi-src:ha-datacenter/APP-DB-01/APP-DB-01.vmx    vmx   import  644245094400     0
esxi-src:ha-datacenter/OLD-FS-02/OLD-FS-02.vmx    vmx   import  2199023255552    0

Importing a VM

In the GUI the flow is: select the VM under the ESXi storage, choose Import, and fill in the dialog. The wiki notes that most configuration is mapped automatically, with the Advanced tab exposing the two things you will usually want to change: the network model and the disk controller per disk.

Set these at import time, not afterwards

Four settings are much cheaper to get right in the dialog than to change on a guest that has already booted once:

Disk controller. VirtIO SCSI (single) is the target for modern Linux guests. For Windows, the controller you pick at import must be one the guest can boot from — which for VirtIO means the driver has to be present in the image already. If it is not, import onto SATA or IDE, boot, install the VirtIO drivers, then switch the controller. Part XXI’s Windows material and the VirtIO driver work cover the detail; the point here is that the decision belongs at import.

Firmware. A VM that was EFI on ESXi needs OVMF and an EFI disk on Proxmox. A BIOS guest needs SeaBIOS. Getting this wrong produces a guest that does not boot, with no useful message.

Network model. VirtIO for anything that can use it; e1000 as the compatibility fallback. The MAC address is worth carrying across deliberately if anything — DHCP reservations, licensing, firewall rules — is keyed to it.

Machine type. q35 for EFI and modern guests, i440fx for older ones. This one is genuinely awkward to change later on Windows.

Service impact possibletidy up a freshly imported guest before first boot— Modifies the imported guest. Sets the QEMU guest agent flag, a sensible boot order and discard on the disk. Review qm config first — do not apply settings blindly to a guest whose imported configuration you have not read.

VMID=310

qm config "$VMID"

qm set "$VMID" --agent enabled=1
qm set "$VMID" --scsi0 shared-rbd:vm-310-disk-0,discard=on,ssd=1
qm set "$VMID" --boot order=scsi0

qm config "$VMID"

The four documented limitations

The wiki names these, and every one of them is worth checking against your estate before you plan a migration around the wizard.

Limitation	What it means for you
vSAN-backed disks cannot be imported	If the source estate runs vSAN, the wizard is not your path. This is the biggest single exclusion
Datastores with special characters (such as `+`) may fail	Check datastore names early; renaming a datastore on the source is usually easier than working around it
Disks encrypted through a Storage Policy are unsupported	VM encryption has to be removed on the ESXi side first
VMs with snapshots import considerably slower	Consolidate snapshots on the source before importing. This is good hygiene regardless

The wiki also records that import was tested against ESXi 6.5 up to 8.0, and that the VM must be powered down before the import starts.

Powered down means the window is the copy

This is the single most important planning consequence and it is easy to read past.

The wizard is not a live migration. The source VM is stopped, its disks are copied across the network into Proxmox storage, and the workload is down for the whole of that copy. For a 2 TB file server over a 1 Gbit/s link that is hours, not minutes.

So the arithmetic for every guest is the same one as any cross-estate move: total disk size divided by usable link bandwidth, plus time to boot and verify at the destination. Size the window from that number and not from how long the dialog takes to fill in.

Two things reduce it. Trim or clean the guest before the move so there is less to copy. And migrate in waves, smallest and least critical first, so the estimate you use for the big guests comes from measurement rather than arithmetic.

Under the hood

What is the plugin actually doing?

It is a storage plugin, and that is the whole trick. Proxmox VE’s storage abstraction — the one in Part V — defines a set of operations a backend must support: list volumes, report status, resolve a volume to something readable. The esxi type implements enough of that against an ESXi host’s API and datastore layout to make the host’s VMs appear as volumes with the import content type.

Because they are volumes in the ordinary sense, everything downstream works without new machinery: the GUI resource tree shows them, the import dialog reads the .vmx to pre-fill guest settings, and the actual transfer is the same disk-import path (qm disk import) that the manual route uses. There is no separate migration engine.

Two consequences follow directly, and they explain most of the limitations.

Whatever the plugin cannot read, it cannot import. vSAN storage is not a datastore the plugin can traverse in the same way, and a disk encrypted by a Storage Policy is unreadable without the key material that lives in vCenter’s key management. Neither is a Proxmox defect; both are the plugin honestly reporting that it cannot open the file.

Snapshots make the disk a chain. A VM with snapshots on ESXi has its data spread across a base disk plus delta files, and reading a consistent image means walking the chain — which is why the wiki notes such imports are considerably slower. Consolidating on the source turns the chain back into one file and the import back into a straight copy.

The neat consequence of the plugin design is that pvesm list esxi-src works from the command line, so a migration inventory is one command rather than a click through a dialog per VM.

Wizard or `virt-v2v`?

	ESXi import wizard	`virt-v2v` / manual export
Intermediate storage needed	No	Yes, usually the full disk size
Steps you run yourself	One	Export, convert, create, attach
Guest OS driver injection	No — you install drivers after boot	`virt-v2v` can inject VirtIO drivers during conversion
vSAN sources	Not supported	Works, via an export from vSphere
Encrypted disks	Not supported	Decrypt on the source either way
Bulk scripting	`pvesm list` plus the API	Established scripted workflows
Source downtime	Yes, for the copy	Yes, for the export

The practical guidance: start with the wizard. It removes the step that consumes the most scratch space and the most operator time, and for most estates it simply works. Keep virt-v2v for the cases the wizard excludes — vSAN, encryption, and any guest where injecting drivers during conversion is easier than installing them after boot, which in practice means older Windows.

And whichever you use, the migration plan around it is the same, which is the subject of the next lesson.

A pre-flight check for the wizard

Run through this once for the estate, before promising anyone a schedule.

Is the source on vSAN? If yes, stop here and plan for virt-v2v.
Are any VMs encrypted via Storage Policy? They need decrypting on the ESXi side first.
Do any datastore names contain characters like +? Rename on the source if practical.
Which VMs have snapshots? Consolidate them before the migration window, not during it.
What ESXi version? Import is documented as tested from 6.5 to 8.0.
What is the link bandwidth between the ESXi host and the Proxmox nodes? Measure it; do not take the switch port speed as the answer.
Sum the disk sizes per wave and divide by that measured bandwidth. That is your window.
Which guests are Windows, and do their images already contain VirtIO drivers? If not, plan the SATA-first, switch-controller-after path.
Which guests have MAC-keyed dependencies — DHCP reservations, licensing, firewall rules? Carry the MAC deliberately for those.
Create a dedicated ESXi account for the migration, and diarise removing both it and the esxi storage when the campaign ends.

What happens if an import fails halfway?

Less than with most migration paths, because the source is untouched.

The source VM is intact. The plugin reads from ESXi; it does not modify anything there. Whatever happened, the original is still on the ESXi host and can be powered back on. That is a genuinely good rollback and it is why the wizard is a comfortable first attempt.

The destination may hold a partial guest. A VMID may have been allocated and one or more disks partially written. Those disks consume space on the target storage and nothing will reclaim them for you.

The recovery order:

Bring the workload back up on ESXi if the outage matters. The window you planned is spent; take the pressure off before diagnosing.
Read the task log on the Proxmox node that ran the import. The reasons divide neatly: a documented limitation (vSAN, encryption, a datastore name), a capacity problem at the destination, a credential or certificate problem, or a network interruption during a long copy.
Remove the partial guest and check for orphaned volumes with pvesm list <target-storage> --vmid <vmid>, freeing anything the removed guest configuration left behind.
Fix the cause and retry, or switch that guest to the virt-v2v path if the cause is one of the documented exclusions.

The failure mode that is not a failure: an import that completes and then the guest does not boot. That is almost always firmware or controller — an EFI guest imported onto SeaBIOS, or a Windows guest on a VirtIO controller whose driver is not in the image. Neither is a transfer problem, and both are fixed with qm set and a reboot rather than by importing again.

Key takeaways

Proxmox VE has an esxi storage plugin. pvesm add esxi <id> --server --username --password makes an ESXi host’s VMs appear as importable volumes with the import content type.
skip-cert-verification exists for self-signed ESXi certificates. Treat it as a recorded decision, and remove the storage and the migration account when the campaign ends.
Most configuration is mapped automatically; the Advanced tab is where you set the network model and the per-disk controller. Firmware and machine type are the other two settings to get right before first boot.
The four documented limitations: vSAN-backed disks cannot be imported, datastores with special characters may fail, Storage-Policy-encrypted disks are unsupported, and VMs with snapshots import considerably more slowly. Import is documented as tested against ESXi 6.5 to 8.0.
The source VM must be powered down. The outage is the disk copy: total disk size over measured link bandwidth, plus boot and verification.
The plugin is a storage backend, so the transfer reuses the ordinary disk import path. What it cannot read, it cannot import — which is exactly the shape of the limitations.
A failed import leaves the source intact on ESXi. Clean up the partial guest and its orphaned volumes at the destination before retrying.
Start with the wizard; keep virt-v2v for vSAN, encrypted disks, and guests where driver injection during conversion is easier than installation after boot.

Knowledge check

Why this matters

The wizard is a good example of a feature whose value is mostly in what it removes.

The old path needed somewhere to put a 2 TB export, an operator to run the conversion, a place to keep the intermediate file, and a way to clean it all up afterwards — and every one of those was a chance to run out of space, get a filename wrong, or leave 2 TB of scratch on a storage nobody was watching. The wizard deletes all of it by making the source host a storage backend.

What it does not remove is the planning, and that is the trap. Because the mechanics got easier, migrations get scheduled as though the whole thing got easier — and the source VM still has to be powered off, the disks still have to cross a network at whatever speed that network actually delivers, and the guest still needs the right firmware and the right drivers on the other side.

Use the wizard. Plan the migration as though you were doing it the old way.