How to Migrate VMs Between Separate Proxmox VE Clusters (Remote Migration)

Why Remote Migration Exists

Every Proxmox VE cluster eventually runs into a scenario that "live migration" was never designed to solve. Live migration — the familiar drag-and-drop VM move you get with qm migrate — only works between nodes that already share a cluster: the same corosync ring, the same quorum, usually the same shared storage. It has nothing to offer you when the two Proxmox environments are, and need to remain, completely separate clusters.

That situation is more common than it sounds. You might be:

• Consolidating two independently built Proxmox clusters after a company merger or datacenter migration, without wanting to physically join them into one corosync group first.
• Splitting a single overloaded cluster into two smaller, independently managed clusters (for example, separating production and staging).
• Moving workloads to new hardware in a different datacenter or region, where stretching a cluster over WAN latency is not viable.
• Handing a set of VMs to a customer or a different team who run their own, unrelated Proxmox VE cluster.

Since Proxmox VE 7.x, the qm remote-migrate and pct remote-migrate commands solve exactly this problem: they move a VM or LXC container — disks, configuration, and optionally memory state — directly from a node in one cluster to a node in a completely unrelated cluster, over the Proxmox API, with no need to ever join the two clusters together. This article walks through the entire process end to end: prerequisites, API token setup, bridge and storage mapping, the actual migration commands for both VMs and containers, and the troubleshooting steps you'll almost certainly need the first time you try it.

Heads up: As of Proxmox VE 9.2, remote migration is still flagged experimental in the official documentation. It works well in practice for the vast majority of standard VMs and containers, but you should test it against a disposable guest before relying on it for anything business-critical, and always keep a backup of the source guest until you've confirmed the target boots correctly.

How Remote Migration Differs From Everything Else You've Used

It's worth being precise about what remote migration is not, because it's easy to confuse it with three other Proxmox VE workflows that look similar on the surface:

Method	Source and target	Requires shared storage?	Requires common cluster?
qm migrate (live migration)	Two nodes in the same cluster	No (with local storage + replication or shared storage)	Yes
qm remote-migrate	Two nodes in different, unrelated clusters	No	No
ESXi/Import Wizard	A foreign hypervisor (VMware) into Proxmox VE	No	No (different hypervisor entirely)
Backup + Restore (PBS or vzdump)	Any two hosts, via a backup datastore	No, but requires a backup step and downtime	No

Remote migration is the only one of these that moves a running guest directly, host-to-host, over the network, authenticated purely by an API token — no cluster join, no temporary storage mount, no export/import file handling. That's what makes it useful for one-off cross-cluster moves where setting up shared storage or merging clusters would be overkill.

Prerequisites

Before you attempt your first remote migration, confirm the following on both the source and target clusters:

• Network reachability on port 8006. The source node initiates an HTTPS connection to the target node's API on TCP 8006. If the clusters sit in different datacenters, this usually means a VPN tunnel, a firewall rule opened between the two public/WAN IPs, or a site-to-site connection. The migration traffic (disk data and, for live migrations, RAM state) also flows over this same connection unless you configure a separate migration network.
• Compatible Proxmox VE versions. Remote migration works best between hosts running the same major Proxmox VE release (e.g., 9.x to 9.x). Cross-major-version migrations (8.x to 9.x) may work for simple guests but are far more likely to hit compatibility snags — QEMU machine-type mismatches being the most common.
• Target storage that can hold the disk format being migrated. If the source VM uses qcow2 on a directory-based storage, the target storage needs to support the same (or the migration engine needs to be able to convert it, which it will attempt for compatible storage types).
• No cluster-specific dependencies on the guest. HA-managed resources, VMs with PCI/GPU passthrough tied to specific host hardware, and VMs relying on cluster-local resources (certain SDN zones, cluster-only storage like Ceph RBD without a matching pool on the target) need extra planning or manual reconfiguration after the move.
• Root or PVEAdmin-equivalent access on both ends to create tokens, read fingerprints, and run the migration CLI.

Step 1: Create an API Token on the Target Cluster

Remote migration authenticates purely via an API token — there's no interactive login involved. Create the token on the target node (the destination cluster), not the source.

1. In the Proxmox VE web UI on the target cluster, go to Datacenter → Permissions → API Tokens.
2. Click Add. Set User to root@pam (or a dedicated migration user if you'd rather not use root — see the security note below).
3. Give the token an ID, for example migrate.
4. Uncheck "Privilege Separation" if you want the token to inherit the full permissions of the user it belongs to. If you leave privilege separation on, you must explicitly grant the token its own permissions in the next step.
5. Click Add and immediately copy the Secret value shown — Proxmox will not show it to you again.

Next, grant the token permission on the resources it needs to touch:

1. Go to Datacenter → Permissions → Add → API Token Permission.
2. Set Path to / (root), select the token you just created, and assign the Administrator role.

Security note: Granting Administrator at the root path is the simplest way to get remote migration working, but it's broad. If you're doing this regularly or in a security-sensitive environment, create a dedicated non-root user (e.g., migration@pve), assign it a custom role scoped to VM.Allocate, VM.Config.Disk, VM.Migrate, Datastore.AllocateSpace, and Datastore.Audit on the specific storage and resource pool it needs, and issue the token from that user instead. Delete or disable the token once your migration project is finished.

Step 2: Get the Target Host's Certificate Fingerprint

Unless the target node's web certificate is signed by a CA your source node already trusts (rare in a self-hosted homelab or SMB setup), you need to pass the target's TLS fingerprint explicitly so the migration command doesn't fail on certificate verification.

Run this on the target node:

openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -sha256 -fingerprint

You'll get output like:

sha256 Fingerprint=AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90

Copy the fingerprint value (without the sha256 Fingerprint= prefix) — you'll pass it as-is into the migration command.

Step 3: Plan Your Bridge and Storage Mapping

Remote migration requires you to explicitly tell it how to map the source VM's network bridge(s) and storage volume(s) to equivalents on the target. There is no auto-detection based on naming conventions unless you use the special shortcut value.

• Bridge mapping (--target-bridge): pass the name of a single bridge on the target (e.g. vmbr0) and every source bridge used by the guest is mapped to it. Alternatively, pass 1 to map each source bridge to an identically-named bridge on the target (useful if both clusters use the same naming convention, like vmbr0/vmbr1 on both sides).
• Storage mapping (--target-storage): same logic — pass a single target storage ID to consolidate all disks onto it, or 1 to map by matching storage names.

Check what's available on the target before you run the migration:

# On the target node
pvesm status
ip link show type bridge

If the source VM has disks split across two storages (say, a fast NVMe pool and a slower HDD pool) and the target cluster only has one comparable storage, you'll need to consolidate — remote migration will move everything to whatever single target storage ID you specify unless you use per-disk overrides (see the CLI reference below for the advanced per-volume mapping syntax).

Step 4: Migrate a Virtual Machine

With the token, fingerprint, and mappings in hand, run the migration from the source node. The full syntax is:

qm remote-migrate <vmid> [<target-vmid>] <target-endpoint> \
  --target-bridge <bridge> --target-storage <storage> [OPTIONS]

The target-endpoint argument is a single comma-separated string bundling the connection details:

apitoken=PVEAPIToken=root@pam!migrate=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=203.0.113.10,fingerprint=AB:CD:12:34:...

Example: offline migration of VM 101

qm remote-migrate 101 101 \
  'apitoken=PVEAPIToken=root@pam!migrate=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=203.0.113.10,fingerprint=AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90' \
  --target-bridge vmbr0 \
  --target-storage local-lvm

This shuts the VM down if it's running, transfers the disks and configuration, and creates VM 101 on the target cluster with the same ID. The source VM is left in place (stopped) by default — nothing is deleted unless you add --delete.

Example: live (online) migration with a bandwidth cap

qm remote-migrate 101 201 \
  'apitoken=PVEAPIToken=root@pam!migrate=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=203.0.113.10,fingerprint=AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90' \
  --target-bridge 1 \
  --target-storage 1 \
  --online \
  --bwlimit 51200 \
  --delete

Here we're doing several things differently:

• Assigning a new VMID (201) on the target instead of reusing 101, avoiding a possible collision with an existing guest.
• --target-bridge 1 and --target-storage 1 map source resources to identically-named ones on the target rather than consolidating to a single name.
• --online keeps the VM running throughout — Proxmox streams memory state across, similar to a normal live migration, so downtime is limited to a brief final cutover.
• --bwlimit 51200 caps transfer at 50 MiB/s (the value is in KiB/s), which matters a lot if the two clusters are connected over a shared WAN link and you don't want the migration to saturate it.
• --delete removes the original VM from the source cluster automatically once the migration completes successfully. Leave this off the first few times you use remote migration until you trust the process.

You'll see live progress in the task log, viewable from Datacenter → Tasks on the source node, or by tailing the CLI output directly — the command blocks and streams status until the migration finishes or fails.

Step 5: Migrate an LXC Container

Containers use the equivalent pct remote-migrate command, with the same target-endpoint, bridge, and storage mapping syntax:

pct remote-migrate 301 301 \
  'apitoken=PVEAPIToken=root@pam!migrate=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=203.0.113.10,fingerprint=AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90:AB:CD:12:34:EF:56:78:90' \
  --target-bridge vmbr0 \
  --target-storage local-zfs \
  --restart \
  --timeout 300

Two options are specific to containers:

• --restart — because LXC containers don't support the same live-memory-transfer path QEMU VMs do, "online" container migration works by briefly stopping the container, transferring its filesystem, and restarting it on the target. This flag opts into that restart-based workflow instead of requiring you to stop the container manually first.
• --timeout <seconds> — how long to wait for the container to shut down cleanly before the migration proceeds (default 180 seconds). Bump this up for containers running services with slow, graceful shutdown routines (databases, message queues).

Everything else — --bwlimit, --delete, target-vmid — behaves identically to the VM version.

Step 6: Verify and Clean Up

Once the task completes, log into the target cluster's web UI and confirm:

• The guest appears with the expected VMID, name, and resource allocation (CPU, RAM, disks).
• It boots correctly and network connectivity works over the mapped bridge — check the guest actually gets an IP and can reach the gateway, since a bridge mapping mismatch is the most common post-migration surprise.
• Any VM-specific integrations that reference the old cluster — monitoring agents, backup job assignments in PBS, firewall rules referencing the old node name — are updated to point at the new location.

If you didn't pass --delete and everything checks out, remove the stopped source copy manually once you're satisfied:

# On the source node, after confirming the migrated copy works
qm destroy 101

Don't rush this step. Keeping the stopped source VM around for a day or two costs you nothing but disk space, and it's your fastest rollback path if something on the target turns out to be misconfigured.

Troubleshooting Common Failures

"Certificate verification failed" or fingerprint mismatch

The fingerprint you supplied doesn't match the target node's current certificate — either it was copied incorrectly, or the target's certificate has been regenerated since you captured it (this happens automatically if you rejoin a node to a cluster, reinstall, or manually reset the pveproxy certificate). Re-run the openssl x509 command on the target and update the value.

"Permission check failed" or 403 responses

The API token doesn't have sufficient rights on the target. Double check the token has an explicit permission entry under Datacenter → Permissions with path / and the Administrator role (or the specific granular roles if you scoped it down), and that privilege separation settings match what you intended.

Migration hangs or times out on large disks

Remote migration transfers the entire disk image over the API connection — there's no delta-sync like PBS backup jobs use. For very large disks over a slow WAN link, this can take hours. Use --bwlimit deliberately (don't leave it unset on a shared WAN uplink), and consider running the migration during a low-traffic maintenance window. For extremely large VMs, it's often faster to do an offline vzdump backup, physically transport or rsync the backup file to the target, and restore locally instead.

"Storage type not supported for migration" or disk conversion errors

Not every storage backend combination can be migrated directly. Ceph RBD-to-Ceph RBID across genuinely separate Ceph clusters, for instance, needs both ends to expose compatible storage plugins, and some raw block storage types don't support the streaming format remote migration relies on. If you hit this, migrate to a intermediate storage type (like a directory/qcow2 storage) on the source first, or fall back to backup-and-restore.

VM boots but has no network connectivity

Almost always a bridge mapping issue — double-check that the bridge name you passed to --target-bridge actually exists on the target node and is configured with the VLANs/subnets the guest expects. If you migrated with --target-bridge 1 assuming matching names, verify the target really does have an identically named bridge; if not, the migration will fail outright rather than silently misconfigure it.

PCI passthrough or GPU-attached VMs fail to migrate

Hardware passthrough devices are tied to the physical host they're attached to and cannot be migrated remotely (or live-migrated at all, even within a cluster). Remove the passthrough device from the VM configuration before migrating, then reattach an equivalent device on the target host manually afterward if one is available.

Limitations to Keep in Mind

• Experimental status. Proxmox's own documentation flags this feature as experimental. Treat it as a powerful but not yet fully hardened tool — test thoroughly, and have a rollback plan (the stopped source guest, or a fresh backup) for anything important.
• HA-managed resources need to be removed from the HA resource manager before migration and re-added on the target if you want HA protection there.
• Snapshots are generally not preserved. Only the current disk state migrates; existing VM snapshots on the source typically do not carry over. If snapshot history matters, take a backup instead of (or in addition to) relying on remote migration.
• Cross-version migrations between significantly different Proxmox VE releases can hit QEMU machine-type or feature mismatches. Staying on matching major versions avoids most of this.
• No built-in scheduling or bulk UI as of Proxmox VE 9.2 — remote migration for many guests at once means scripting the CLI command in a loop, since the mainline web UI wizard is limited to per-guest actions.

Frequently Asked Questions

Do the source and target clusters need to be on the same network?

No, but they do need routable connectivity to each other on TCP 8006 (and the migration traffic itself, which flows over that same connection unless you configure a dedicated migration network). A site-to-site VPN or WireGuard tunnel between datacenters works fine.

Can I migrate a VM back the same way once it's on the new cluster?

Yes — remote migration is symmetric. You'd simply create a token on what is now the "target" (the original source cluster) and run the command in the opposite direction.

Does remote migration work between a standalone node and a cluster?

Yes. Neither side needs to be a multi-node cluster; a single standalone Proxmox VE host works as either the source or the target endpoint.

Is downtime required?

Not for VMs if you use --online — the guest keeps running while its memory state streams across, with only a brief pause during final cutover, similar to intra-cluster live migration. Containers using --restart will have a short outage while they stop, transfer, and restart. Omitting --online/--restart does a clean offline migration with the guest shut down for the full transfer window.

What happens to the VMID if it's already taken on the target?

The migration fails with a conflict error. Always specify an explicit target-vmid if there's any chance of a collision, rather than relying on the source VMID being free on the target.

Can I migrate between a Proxmox VE 8 cluster and a Proxmox VE 9 cluster?

It can work for simple, standard guests, but it's more failure-prone than same-version migrations due to QEMU and feature differences between releases. If you're planning a cluster consolidation project, it's worth upgrading both ends to the same major version first if your timeline allows it.

Does this replace backups?

No. Remote migration moves a guest's current state; it isn't a substitute for scheduled backups via Proxmox Backup Server. Keep your normal backup jobs running independently of any migration project.

Conclusion

Remote migration fills a real gap in the Proxmox VE toolkit: moving guests between clusters that were never meant to be joined, without the overhead of cluster merges or the downtime of a full backup-and-restore cycle. The setup — an API token, a certificate fingerprint, and explicit bridge/storage mappings — is a bit more manual than the one-click live migration you get inside a single cluster, but once you've done it once, scripting it for a handful of guests at a time is straightforward. Start with a low-stakes test VM, confirm the whole round trip works end to end on your specific network and storage setup, and only then move on to guests that actually matter.