14.13.6. Configuring Virtual CPU Count

To modify the number of CPUs assigned to a guest virtual machine, use the virsh setvcpus command:
# virsh setvcpus {domain-name, domain-id or domain-uuid} count [[--config] [--live] | [--current] [--guest] 
The following parameters may be set for the virsh setvcpus command:
  • {domain-name, domain-id or domain-uuid} - Specifies the virtual machine.
  • count - Specifies the number of virtual CPUs to set.

    Note

    The count value cannot exceed the number of CPUs that were assigned to the guest virtual machine when it was created. It may also be limited by the host or the hypervisor. For Xen, you can only adjust the virtual CPUs of a running domain if the domain is paravirtualized.
  • --live - The default option, used if none are specified. The configuration change takes effect on the running guest virtual machine. This is referred to as a hot plug if the number of vCPUs is increased, and hot unplug if it is reduced.

    Important

    The vCPU hot unplug feature is a Technology Preview. Therefore, it is not supported and not recommended for use in high-value deployments.
  • --config - The configuration change takes effect on the next reboot of the guest. Both the --config and --live options may be specified together if supported by the hypervisor.
  • --current - Configuration change takes effect on the current state of the guest virtual machine. If used on a running guest, it acts as --live, if used on a shut-down guest, it acts as --config.
  • --maximum - Sets a maximum vCPU limit that can be hot-plugged on the next reboot of the guest. As such, it must only be used with the --config option, and not with the --live option.
  • --guest - Instead of a hot plug or a hot unplug, the QEMU guest agent modifies the vCPU count directly in the running guest by enabling or disabling vCPUs. This option cannot be used with count value higher than the current number of vCPUs in the gueet, and configurations set with --guest are reset when a guest is rebooted.

Example 14.4. vCPU hot plug and hot unplug

To hot-plug a vCPU, run the following command on a guest with a single vCPU:
virsh setvcpus guestVM1 2 --live
This increases the number of vCPUs for guestVM1 to two. The change is performed while guestVM1 is running, as indicated by the --live option.
To hot-unplug one vCPU from the same running guest, run the following:
virsh setvcpus guestVM1 1 --live
Be aware, however, that currently, using vCPU hot unplug can lead to problems with further modifications of the vCPU count.