Migration moves a guest from one node of your cluster to another, for example to empty pve1 before maintenance. A running virtual machine moves live, with a pause of well under a second. Before you choose a destination, Aprox asks Proxmox which nodes can take the guest and explains why the others cannot. Migration is part of Aprox Pro and needs a cluster with more than one node.

Where to find it

  • Sidebar › plex › Summary › Actions › Migrate. The button is disabled when no other node is online.
  • Or long-press the guest in the sidebar (right-click on a Mac) › Migrate….

On the free plan the button carries a lock (menus show "(Pro)"), and tapping it opens an overview of Aprox Pro.

Migrate a guest

  1. Open Migrate. Aprox first shows Asking the cluster what is possible… while Proxmox checks the guest against every node.
  2. Under Destination, choose the target node, for example pve2.
    • Nodes that cannot take the guest are listed under Nodes that cannot take it, each with the reason, for example Cannot reach storage: local-lvm or Blocked by high-availability rules: ….
    • If no node qualifies, Aprox says No node in this cluster can take this guest right now.
  3. Check the Mode section. Guest is shows Running or Stopped, and the text below explains what happens:
    • Running virtual machine: live migration. "The guest keeps running throughout. Its memory is copied across and it switches nodes at the end, with a pause of well under a second."
    • Running container: containers cannot move live. Turn on Restart on the target node: "The container is shut down, moved, and started again on the target node. It is unavailable while that happens." Without it, you have to shut the container down first.
    • Stopped guest: "The guest is stopped, so only its disks move. It stays stopped afterwards."
  4. If the guest has Local disks, that is, disks on storage that only the current node can see, they must be copied to the target node. Optionally:
    • choose a Target storage on the destination; leave it unset to keep each disk on a storage with the same name there;
    • set a Speed limit in MiB/s, so the copy does not saturate your network. The default is Unlimited.
  5. Tap Migrate. Aprox shows Starting the migration… and closes the sheet once Proxmox has accepted the job.

Follow the migration

  • iPhone: a Live Activity shows "Migrating …" with its progress. See Live Activities.
  • Android: a progress notification.
  • Everywhere: the task and its live log in the guest's Tasks tab and in Cluster Tasks.

When the migration finishes, the guest appears under its new node in the sidebar.

When a guest cannot be migrated

Situation What Aprox shows What to do
Running VM with PCI or USB passthrough "This guest has hardware passed through to it, so it cannot be migrated while it is running. Shut it down first." Shut the guest down and migrate it stopped. It will not start on the target node unless the same hardware is there.
A disk is on storage the target cannot reach Cannot reach storage: … Choose another node, or make the storage available on that node.
High availability rules pin the guest Blocked by high-availability rules: … Adjust the HA rules in the Proxmox web UI.
Only one node online There is no other node in this cluster to migrate to. Bring another node online first.

Requirements on the server

  • Privilege: typically VM.Migrate on the guest.
  • A cluster with at least two online nodes.
  • Live migration of a VM works best with its disks on shared storage, such as Ceph or NFS. With local disks, Proxmox copies every byte across, which takes longer.

Good to know

  • Same CPU type. For live migration between nodes with different processors, use a CPU type that both support, such as x86-64-v2-AES, rather than host. See Virtual machine hardware.
  • Demo. In the demo cluster, a migration between pve1 and pve2 really runs, taking about 25 seconds with progress.