Visit Apps Ved →

qm-remote-migrate

Migrate a Proxmox VM to a remote host or cluster

TLDR

Migrate a VM to a remote host
$ qm remote-migrate [vmid] [target_vmid] 'apitoken=PVEAPIToken=[user]@[realm]![token]=[secret],host=[address],fingerprint=[fingerprint]' --target-bridge [bridge] --target-storage [storage]
Migrate a running VM with live migration
$ qm remote-migrate [vmid] [target_vmid] 'apitoken=PVEAPIToken=[user]@[realm]![token]=[secret],host=[address],fingerprint=[fingerprint]' --target-bridge [bridge] --target-storage [storage] --online
Delete the source VM after a successful migration
$ qm remote-migrate [vmid] [target_vmid] 'apitoken=PVEAPIToken=[user]@[realm]![token]=[secret],host=[address],fingerprint=[fingerprint]' --target-bridge [bridge] --target-storage [storage] --delete 1
Limit migration bandwidth
$ qm remote-migrate [vmid] [target_vmid] 'apitoken=PVEAPIToken=[user]@[realm]![token]=[secret],host=[address],fingerprint=[fingerprint]' --target-bridge [bridge] --target-storage [storage] --bwlimit [value]
Use the same bridge and storage names on the target
$ qm remote-migrate [vmid] [target_vmid] 'apitoken=PVEAPIToken=[user]@[realm]![token]=[secret],host=[address],fingerprint=[fingerprint]' --target-bridge 1 --target-storage 1

SYNOPSIS

qm remote-migrate vmid target-vmid target-endpoint [OPTIONS]

DESCRIPTION

qm remote-migrate migrates a virtual machine from the local Proxmox VE cluster to a remote host or cluster over the Proxmox API. Unlike `qm migrate` (intra-cluster), remote migration uses an API token and host fingerprint for authentication and TLS verification.You must supply bridge and storage mapping so network and disks land on valid remote resources. Live migration (`--online`) moves a running guest with reduced downtime when the environments support it.

PARAMETERS

vmid

Source virtual machine ID on the local cluster
target-vmid
Destination VM ID on the remote cluster (may match source)
target-endpoint
Remote connection string: API token, host, TLS fingerprint (optional port)
--target-bridge bridge|1
Map network bridges; `1` keeps source bridge names
--target-storage storage|1
Map storage; `1` keeps source storage names
--online
Perform online/live migration for a running VM
--delete 0|1
Remove the source VM after a successful migration
--bwlimit kbps
Bandwidth limit for the transfer

CAVEATS

Requires a valid API token with sufficient privileges on the remote side and a matching TLS fingerprint. Network capacity and storage compatibility dominate transfer time. Test mappings carefully; wrong bridge/storage targets fail mid-migration. Treat API tokens as secrets.

HISTORY

Part of Proxmox VE QEMU/KVM management, enabling cross-cluster VM moves without shared cluster membership.

SEE ALSO

qm(1), qm-migrate(1), pvecm(1)

RESOURCES

Homepage · Documentation