Exporting out of Proxmox · Proxmox VE

Every lesson in this part so far has been about arriving. This one is about leaving, and it belongs in the course for the same reason a building has fire exits: not because you expect to use it, but because a route you have never walked is not a route.

It is also the lesson that makes the rest of the part honest. A course that teaches migration to a platform and is silent about migration from it is selling something.

What Proxmox actually offers

Start with the uncomfortable fact. Proxmox VE has qm importovf and qm disk import. It has no matching export command. There is no qm exportovf, and there is no single operation that produces a portable appliance from a running guest.

That is not a gap in the product so much as an accurate reflection of what a virtual machine is: a disk image plus a hardware description, where only the first half is portable. So the export is two jobs.

What you need	How you get it
The disk data	`qemu-img convert` from the path `pvesm path` resolves
The guest definition	Read `qm config`, and rebuild it on the destination
A container’s filesystem	`vzdump`, which produces a tar of the root filesystem
The backup archives themselves	PBS and `vzdump` formats are Proxmox-specific

Converting a disk

Read-only / Safefind out what and where the disk actually is— Read-only. qm config names the volume; pvesm path resolves it to a file or block device; qemu-img info reports the real format and the actual allocated size, which is what determines how long the conversion takes and how much space it needs.

VMID=141

qm config "$VMID" | grep -E '^(scsi|virtio|sata|ide|efidisk|tpmstate)[0-9]'

qm status "$VMID"

VOL="$(qm config "$VMID" | sed -n 's/^scsi0: \([^,]*\).*/\1/p')"
pvesm path "$VOL"

qemu-img info "$(pvesm path "$VOL")"

Read-only / Safe

$ qemu-img info /dev/zvol/rpool/data/vm-141-disk-0

image: /dev/zvol/rpool/data/vm-141-disk-0
file format: raw
virtual size: 500 GiB (536870912000 bytes)
disk size: 0 B

Service impact possibleconvert a stopped guest's disk to a portable image— Requires the guest to be STOPPED. Converting a running guest's disk produces a crash-consistent image at best and a corrupt one at worst. -p shows progress; -O selects the output format. Ensure the destination has room for the full converted size.

VMID=141
OUT=/srv/export

qm stop "$VMID"
qm status "$VMID"

VOL="$(qm config "$VMID" | sed -n 's/^scsi0: \([^,]*\).*/\1/p')"
SRC="$(pvesm path "$VOL")"

qemu-img convert -p -O qcow2 "$SRC" "${OUT}/vm-${VMID}-disk0.qcow2"

qemu-img info "${OUT}/vm-${VMID}-disk0.qcow2"

The -O argument chooses the destination’s language:

Destination	Format
KVM/libvirt, oVirt, another Proxmox	`qcow2` — thin, snapshot-capable
Anything wanting a bare block image, or a cloud import	`raw`
VMware	`vmdk`
Hyper-V	`vhdx`

Convert while stopped, and budget for the full size

Two constraints that bite in practice.

The guest must be stopped. qemu-img convert reads the disk while the guest may be writing to it, and it has no coordination with the guest’s filesystem. A converted live disk is crash-consistent at best — the state of a machine that lost power mid-write — and inconsistent at worst if the write pattern spans the read. For a database that is not a recovery point, it is a corrupt file that sometimes appears to work.

If downtime is genuinely impossible, snapshot first and convert the snapshot, accepting that the image is as of the snapshot. That is a real recovery point rather than a hopeful one.

The output is usually much larger than you expect. A thin 500 GB disk using 40 GB on ZFS converts to a qcow2 of roughly its written size if the source can report holes, and to a 500 GB raw file if you ask for raw. Trim inside the guest before converting, check the real allocation with zfs list or lvs rather than trusting qemu-img info on a block device, and size the export target from the provisioned figure if you are unsure.

Preparing the guest to arrive, not just to leave

A converted disk is necessary and not sufficient. The guest was configured for QEMU/KVM with VirtIO devices, and the destination may not speak that dialect.

Before you convert, inside the guest

Linux guests are usually easy, because the drivers are in the kernel.

Make sure the initramfs contains drivers for the destination’s storage controller, not only the source’s. dracut --regenerate-all --force or update-initramfs -u -k all, depending on the distribution.
Check that root and other filesystems are referenced by UUID in /etc/fstab and in the bootloader, not by /dev/sdX or by a VirtIO-specific path. This is the commonest reason a converted Linux guest drops to an emergency shell.
Remove or disable the QEMU guest agent if the destination has its own.
Note the firmware — UEFI or BIOS — because the destination must be told.
Trim: fstrim -av, so the conversion has less to copy.

Windows guests need more care, because the storage driver is loaded very early and a missing one is an unbootable machine.

If the destination is not KVM-based, install its integration tools before converting — VMware Tools, or Hyper-V Integration Services — while the guest still runs on Proxmox and can reach the network.
Do not uninstall the VirtIO drivers before you leave. A driver that is present and unused is harmless; a driver that is absent when you need to roll back is an unbootable rollback.
Note the firmware and the machine type, and expect a reactivation prompt: to Windows licensing, this is new hardware.

Both

Record the MAC addresses if anything is keyed to them.
Record the full qm config, which is your only description of the virtual hardware once the guest has left.

Read-only / Safecapture the guest definition before it leaves— Read-only. The guest configuration is the hardware description that has to be recreated on the destination by hand. Save it with the exported disks, in the same directory, so the two never separate.

VMID=141
OUT=/srv/export

qm config "$VMID" --current > "${OUT}/vm-${VMID}.conf"
qm showcmd "$VMID" --pretty > "${OUT}/vm-${VMID}.qemu-cmdline.txt"

cat "${OUT}/vm-${VMID}.conf"

Read-only / Safe

$ qm config 141 --current

agent: enabled=1
bios: ovmf
boot: order=scsi0
cores: 4
cpu: x86-64-v3
efidisk0: local-zfs:vm-141-disk-1,efitype=4m,pre-enrolled-keys=1,size=1M
machine: q35
memory: 8192
name: app-frontend-01
net0: virtio=BC:24:11:1A:2B:3C,bridge=vmbr0,tag=120
numa: 0
scsi0: local-zfs:vm-141-disk-0,discard=on,size=500G,ssd=1
scsihw: virtio-scsi-single
sockets: 1

Containers are the easy case

An LXC container has no virtual firmware, no emulated controller and no driver problem. vzdump produces an archive of its root filesystem plus its configuration, and a root filesystem tarball is the most portable artefact in this entire lesson.

Service impact possibleexport a container— Stops the container for a consistent archive. The resulting tar is a root filesystem plus configuration, which any LXC or LXD host can consume and which can also be unpacked to inspect or to rebuild elsewhere.

CTID=205
OUT=/srv/export

pct shutdown "$CTID" --timeout 120
vzdump "$CTID" --dumpdir "$OUT" --mode stop --compress zstd

ls -lh "$OUT"
pvesm extractconfig "${OUT}/$(ls "$OUT" | grep "lxc-${CTID}-" | tail -1)"

The configuration inside is Proxmox-specific — mount points, resource limits, unprivileged, the network definition — but the filesystem itself is just a filesystem. Where the destination is another LXC host, that is close to a one-step migration.

What does not travel

Does not travel	Consequence
The guest configuration semantics	Firmware, machine type, CPU model, controller and boot order must be recreated by hand
Snapshots	The destination’s snapshot mechanism is different; convert the state you want and abandon the tree, or export several states
Cloud-Init configuration	Proxmox generates a Cloud-Init drive from guest options; the destination has its own mechanism
Firewall rules	`/etc/pve/firewall/<VMID>.fw` is Proxmox configuration
HA membership, pool membership, tags	Cluster configuration, not guest configuration
Backup history	PBS backup groups and `vzdump` archives are Proxmox-specific formats
Replication jobs	`pvesr` is Proxmox-specific
Resource mappings and passthrough	PCI and USB mappings are host and cluster configuration

Backup history is the one that surprises people

Disks convert. Configuration can be retyped. Backup history cannot be moved.

PBS stores deduplicated chunks in its own format, and a vzdump archive is a Proxmox construct. Neither is readable by another hypervisor’s tooling, and there is no conversion path. So an estate leaving Proxmox after four years has four years of restore points that only a Proxmox Backup Server can read.

The practical handling, decided at planning time rather than discovered at decommissioning time:

Keep a PBS instance alive for the retention period the data policy requires, even after the workloads have left. It is a small VM and a datastore; it is far cheaper than the alternative.
Or restore what must be retained and re-archive it in a format the new platform can read — which means restoring guests you no longer run, and costs real time and space.
Or accept the loss, explicitly, with the data owner’s agreement and a record of the decision.

What you must not do is discover this in the month you were planning to switch off the last Proxmox node.

Under the hood

Why is there an import and no export?

Look at what qm importovf does: it parses an OVF manifest — an XML description of virtual hardware — maps that description onto Proxmox’s own guest options as faithfully as it can, and imports the referenced disks. It is a translation into the native model.

Export would be translation out, and the direction is much harder. OVF describes a common subset; a Proxmox guest configuration contains things that subset has no words for — a specific machine version pinned for migration compatibility, a cpu model like x86-64-v3, virtio-scsi-single with iothread, discard and ssd flags per disk, an efidisk with pre-enrolled Secure Boot keys, a tpmstate volume, host PCI mappings. An exporter has to decide what to drop, and whatever it drops silently is a guest that arrives subtly wrong somewhere else.

The same asymmetry exists in every hypervisor, which is why every one of them imports more formats than it exports.

The consequence for you is not that export is impossible — the disk is a file and the configuration is 20 lines of text — but that the translation is yours to do, deliberately, with the destination’s model in front of you. That is a better outcome than a tool that guesses, provided you have done it once and know which lines matter.

Which is exactly the argument for rehearsing the exit while you still have people who know both platforms.

What happens if the exported guest will not boot on the destination?

It is nearly always one of four things, and they are quick to distinguish.

1. Firmware mismatch. The guest was OVMF/UEFI and has been defined as BIOS on the destination, or the reverse. The symptom is no bootloader at all — a black screen, a “no bootable device” message, or a firmware shell. Check the bios: line in the configuration you saved. For a UEFI guest, note that the EFI variable store was a separate efidisk volume on Proxmox and its equivalent on the destination will start empty, so the boot entry may need recreating from the firmware menu.

2. Storage controller. The destination presents a controller the guest has no driver for. On Linux this shows as a kernel panic or a dracut emergency shell complaining it cannot find the root device; on Windows it is INACCESSIBLE_BOOT_DEVICE. The fix is the preparation step you skipped: regenerate the initramfs with broader driver coverage, or on Windows attach the disk to a controller the image already supports and change it afterwards.

3. Device naming in fstab or the bootloader. The root filesystem is referenced by a path that changed. Boot from rescue media, mount, and switch the references to UUID=.

4. The image is fine and the definition is wrong. Wrong machine type, too little memory to boot the installed kernel, or a boot order pointing at an empty device. This is why saving qm config alongside the disks matters: it is the specification you are checking against.

How to tell them apart fast: attach the converted disk to a known-good throwaway guest on the destination as a secondary disk. If its filesystem mounts and the data is intact, the image is fine and the problem is the guest definition. That single test splits the problem in half and takes five minutes.

Why this belongs in a procurement conversation

An exit path is not a comment on the platform. It is a property of the risk, and it is worth stating in those terms:

It is leverage. A platform you can leave is a platform you can negotiate with. A platform you cannot leave sets its own terms at renewal.
It is continuity planning. Vendors change ownership, licensing models and strategy. The estates that suffered most in the 2024 virtualisation upheaval were the ones that had never costed an exit.
It is a testable claim. “We could migrate away in three months” is either a number somebody has derived from a rehearsal, or it is a feeling.
It is cheap while you have the skills. The exit is hardest to rehearse at exactly the moment you most need it, because by then the people who knew the old platform have moved on.

The proportionate version is small: export one representative guest per class — a Linux server, a Windows server, a container — onto the platform you would plausibly move to, boot it, and write down how long it took and what broke. Once a year. That converts an assumption into an estimate, and it is the same exercise this whole part has been describing, run in the other direction.

Key takeaways

Proxmox VE has qm importovf and qm disk import and no matching export command. Leaving is a disk conversion plus a guest definition you rebuild.
pvesm export is documented as used internally and produces a framed stream (qcow2+size, raw+size, vmdk+size, tar+size, zfs, btrfs). For leaving, use pvesm path plus qemu-img convert.
qemu-img convert -O selects the destination’s language: qcow2 for KVM/libvirt, raw for bare images and cloud imports, vmdk for VMware, vhdx for Hyper-V.
Convert only while the guest is stopped. A live conversion is crash-consistent at best. If downtime is impossible, snapshot and convert the snapshot.
Prepare the guest to arrive: initramfs with the destination’s drivers, UUID= references in fstab and the bootloader, destination integration tools installed on Windows before conversion, VirtIO drivers left in place for rollback, and fstrim to shrink the copy.
Save qm config --current beside the exported disks. It is the only description of the virtual hardware once the guest has gone.
Containers are the easy case: vzdump yields a root filesystem tarball, which is the most portable artefact here.
Backup history does not travel. Keep a PBS instance for the retention period, restore and re-archive what must be kept, or record an explicit decision to lose it.
Rehearse the exit annually with one guest per class. It is leverage, continuity planning, and a claim you can defend with a number.

Knowledge check

Why this matters

The reason this lesson exists is not that Proxmox is likely to disappoint you. It is that “how would we leave?” is a question every platform decision should have an answer to, and almost none do — and the cost of not having one is paid years later, by people who did not make the decision.

There is a specific version of this that plays out repeatedly. A platform is chosen, the team becomes expert in it, the previous platform’s skills fade, and by the time an exit is contemplated nobody remembers how the estate got there or what the guests are actually made of. The exit is then not hard because of the technology; it is hard because the knowledge has gone.

An annual half-day — one Linux guest, one Windows guest, one container, exported and booted somewhere else — keeps that knowledge alive and turns a strategic question into an estimate. It is the cheapest insurance in this course, and the only one whose premium is measured in an afternoon.