qm-migrate

Migrate a specific virtual machine

$ qm migrate [vm_id] [target]

$ qm migrate [vm_id] [target] --bwlimit 10

$ qm migrate [vm_id] [target] --force true

$ qm migrate [vm_id] [target] --online true

$ qm migrate [vm_id] [target] --with-local-disks true

qm migrate [OPTIONS]

    The ID of the virtual machine or container to migrate.


    The target Proxmox VE host.

--online
    Perform a live (online) migration. This minimizes downtime. Requires shared storage for best results. Equivalent to `-with-hv`.

--with-local-disks
    Migrate also the local disks. This is usually not needed when using shared storage.

--targetstorage
    Specify the target storage for disks. If not specified, the storage will be automatically selected.

--target
    The target node name. Required for migrations when multiple nodes are possible (e.g. with HA groups).

--delete
    Delete the source VM/container after successful migration.

--migration_network
    Specify the network to use for migration. If not specified, Proxmox VE will automatically choose a suitable network.

--migration_type
    Specify the migration type. Defaults to 'downtime'. 'secure' enforces encryption. 'tcp' and 'unix' dictate transport methods, with unix sockets being faster.

--compress
    Enable compression during migration.

--max_workers
    Number of workers. Defaults to 16. Useful to increase the migration speed.

--restart
    Restart the VM/CT after migration.

--unprotected
    Disable HA protection during the migration. Implies --skiplock.

--skiplock
    Skip locking the VM during the migration. Use with extreme caution, as it can lead to data corruption.

--debug
    Enable debug logging.

--profile
    Select a pre-configured migration profile. See `qm migrate profile`.

--with-hv
    Alias for --online.

The `qm migrate` command is a powerful tool used within the Proxmox Virtual Environment (Proxmox VE) to migrate virtual machines (VMs) and containers between different Proxmox VE hosts. It allows for live or offline migration, minimizing downtime during infrastructure maintenance, upgrades, or hardware rebalancing.

The command facilitates the transfer of VM/container disk images, configuration files, and memory state (in live migration) from a source host to a destination host. It relies on Proxmox VE's cluster functionality and requires a properly configured and healthy Proxmox VE cluster for successful operation. Options control aspects like network configuration, migration speed, compression, and whether the migration should be performed online (live) or offline (stop the VM, then migrate). Successful migration relies on shared storage access between hosts (though this isn't mandatory, it's strongly recommended for live migrations), and ensuring compatible CPU architectures between hosts can be critical for avoiding issues.

The command integrates with Proxmox's High Availability (HA) system to ensure services remain available. It's crucial to carefully plan and test migrations, especially live migrations, to ensure minimal disruption. The command returns zero when everything is correct and non-zero when it fails.

Live migration requires shared storage accessible by both the source and destination hosts for optimal performance and minimal downtime. Incompatible CPU architectures between hosts can prevent successful live migration or cause issues after migration. Ensure the Proxmox VE cluster is healthy before attempting any migrations. Pay special attention when migrating HA configured resources. The --skiplock option can lead to data corruption if not used carefully.

Migration profiles allows you to pre-configure migration settings. This is useful for complex migration scenarios or for automating migration tasks. You can create and manage migration profiles using the `qm migrate profile` command.

Run `man qm` to see all possible parameters for migration profiles.

Ensure that the migration network is properly configured and accessible between the source and destination hosts. Use the `--migration_network` option to explicitly specify the network interface to use for migration traffic. Proper network configuration significantly impacts the speed and reliability of the migration process.

The `qm migrate` command is a core component of the Proxmox VE virtualization platform. It was developed as part of the initial Proxmox VE releases and has been continuously improved over time to enhance migration performance, stability, and feature set. Features such as live migration, support for various storage types, and integration with the Proxmox VE API have been added over the years to meet the evolving needs of users managing virtualized environments. The command's design reflects a focus on providing a flexible and reliable mechanism for moving workloads between Proxmox VE hosts.

qm(1), pvesh(1), pct(1)