QEMU Machine Version Upgrade

Introduction

This page documents specific incompatibilities between QEMU machine versions that can cause issues in guests. Please report any other issues you encounter on our Bugzilla or in the community forum, so they can be documented too.

For general information about QEMU machine types in Proxmox VE, see the corresponding chapter in the Proxmox VE documentation.

Before upgrading the machine version, make sure you have a working backup first. Any change to the machine version may affect how the guest sees its virtual hardware, which may require adjustments such as reinstalling some (VirtIO) drivers in the guest.

Machine Version Upgrade

1. Check the current machine version by going to the VM's Hardware tab and looking at the Machine property. If there is a version suffix, then the VM uses a pinned machine version. For example, pc-i440fx-9.2 has machine version 9.2. If there is no version suffix, that means that the VM is using the latest available machine version automatically. This is the default for non-Windows guests. No further steps need to be taken in that case.
2. Decide which machine version you want to upgrade to. It is recommended to upgrade to the newest available machine version (which is the version of the currently installed QEMU package, i.e. pve-qemu-kvm). You can see the available versions by editing the Machine property and clicking the Version drop-down.
3. See the sections about known issues for the relevant machine versions below. Relevant sections are those for machine versions between the current machine version (excluded) and the target machine version (included). For example, if you update from machine version 4.0 to 9.0, you should consider the sections from 4.1 all the way up to and including the section about 9.0. In particular, you should also consider the section about 5.2.
4. Edit the Machine property and change to the target version. For a currently running VM, the machine version will be applied during the next VM start. You can use the Reboot button in the UI. Rebooting from within the guest is not enough. It is recommended to apply the machine version directly after updating it, to be able to detect potential issues immediately.
5. Follow the suggestions for the known issues from below and check for any other issues. It might be necessary to install/upgrade drivers (e.g. VirtIO) or adapt some hardware configurations.

Known Issues

Machine Version 5.2

This version fixed a bug QEMU's ACPI implementation.

This confuses Windows guests however, as the device enumeration changes. In particular, network adapters will be detected as if they were new, so static settings will be gone and the adapters will start with a default configuration (DHCP). The same applies for non-default settings for other devices (e.g. if DMA was disabled for an ATA controller). The change will also result in hidden duplicate entries for many devices in the Windows Device Manager (i.e. entries for devices under the old enumeration).

Linux and other operating systems do not seem to be impacted negatively by this change.

Machine Version 6.1 for q35 Machine Type

This version enabled ACPI hotplug on PCI bridges by default.

This affects systemd's predictable interface naming. Proxmox VE will automatically work around this for virtual machines with OS type l26 that were created with a QEMU version before 6.1 by keeping ACPI hotplug on PCI bridges disabled.

Windows guests are not known to be impacted negatively by this change.

If you have a non-Linux VM with OS type different from l26 or switched back the machine type after creation for some reason, and the VM is relying on systemd's predictable interface naming, you will need to update the guest's network configuration.