GPU VM Machine Type and OS Compatibility
Overview
GPU VMs — whether using passthrough or vGPU — have additional compatibility requirements beyond those of a standard VM. Machine type (Q35 vs. i440fx), UEFI/OVMF firmware, and the combination of host OS, QEMU, and libvirt versions all affect whether a GPU VM boots successfully.
This page documents the compatibility matrix and common boot failures caused by machine-type or OS mismatches, along with a pre-flight checklist to verify compatibility before deploying GPU VMs.
Machine Type Requirements
Private Cloud Director supports two machine types for virtual machines:
Q35 — the recommended machine type for GPU VMs. Q35 uses PCIe topology and is required for correct PCI passthrough of modern NVIDIA GPUs. It also supports large PCI MMIO windows needed by GPUs with substantial VRAM (for example, H200).
i440fx — the legacy machine type. It uses PCI (not PCIe) topology and may not expose sufficient address space for modern GPU hardware. Some GPU models will not pass the NVIDIA driver's device initialization on i440fx.
For GPU passthrough VMs, always use Q35. If you create a GPU VM with the i440fx machine type and the GPU uses a large MMIO window (such as the H200 or A100), the VM may boot but the NVIDIA driver inside the guest will fail to initialize the GPU, and nvidia-smi will report no devices.
You set the machine type via an image property on the VM image:
pcdctl image set <IMAGE_ID> hw_machine_type=q35Confirm the property is set:
pcdctl image show <IMAGE_ID> | grep hw_machine_typeUEFI/OVMF Firmware
Modern NVIDIA GPU passthrough generally requires UEFI boot (OVMF firmware) rather than legacy BIOS (SeaBIOS), particularly for:
GPUs that enumerate as UEFI-only ROM devices.
Guest OSes using Secure Boot.
Ubuntu 24.04 guests with newer kernel versions.
Set the UEFI firmware via the image property:
If you set hw_firmware_type=uefi without also setting hw_machine_type=q35, the VM may fail to boot because OVMF requires PCIe topology. Always set both properties together for GPU VMs.
Large-BAR GPUs such as the A100 and H200 may also require an enlarged 64-bit PCI/MMIO window for the GPU's memory-mapped region. If a large-BAR GPU VM boots but the GPU is not visible inside the guest (for example, nvidia-smi reports no devices), contact Platform9 Support for the recommended host and flavor configuration for your specific GPU model.
Ubuntu Version Compatibility
The following compatibility notes apply to the host and guest OS versions used with GPU VMs.
Host OS Compatibility
Ubuntu 22.04, kernel 5.15
Supported
Supported
Ubuntu 22.04, kernel 6.5
Supported
Supported
Ubuntu 24.04, kernel 6.8
Supported
Not supported
Ubuntu 24.04, kernel 6.11
Supported
Not supported
vGPU on Ubuntu 24.04 hosts is not currently supported because the default Ubuntu 24.04 LTS packages ship libvirt and QEMU versions that do not yet meet the minimum version requirements for vGPU live migration and full vGPU device attachment. Use Ubuntu 22.04 hosts for vGPU workloads.
Guest OS Compatibility
GPU passthrough is supported with any guest OS that has a compatible NVIDIA driver. vGPU requires the NVIDIA vGPU guest driver, which is available for:
Ubuntu 22.04 LTS (guest)
Ubuntu 24.04 LTS (guest) — requires NVIDIA vGPU guest driver version 550 or later
Ubuntu 24.04 Guests: OVMF Version Constraints
When launching GPU passthrough VMs with an Ubuntu 24.04 guest, use OVMF firmware that is compatible with the QEMU version on the host. On Ubuntu 22.04 hosts, the OVMF package may be an older version. If the guest fails to boot and the console shows:
or gets stuck at the OVMF splash screen, the OVMF version and QEMU version on the host may be mismatched. Update the OVMF package:
After the update, power off the VM and power it on again (a reboot is not sufficient if the firmware blob itself changed).
Pre-Flight Compatibility Checklist
Before deploying a GPU VM, verify all items in this checklist.
Image Properties
Run the following and confirm the values match your requirements:
hw_machine_type
q35
hw_firmware_type
uefi (recommended for passthrough; required for UEFI-only GPUs)
Host Verification
On the GPU host, confirm the following before launching VMs:
QEMU and libvirt Versions
For vGPU live migration support (future capability), the following minimum versions are required on both source and destination hosts:
libvirt 8.6.0 or later
QEMU 8.1.0 or later
Linux kernel 5.18.0 or later
Check the installed versions:
Currently, the default Ubuntu 22.04 LTS packages do not meet the vGPU live migration version requirements. Cold migration of vGPU VMs is the supported approach for moving vGPU workloads between hosts. See GPU FAQs for migration behavior details.
Common Boot Failures and Resolutions
VM boots but nvidia-smi returns no devices in guest
Machine type is i440fx, or a large-BAR GPU needs an enlarged MMIO window
Set hw_machine_type=q35; for large-BAR GPUs (A100/H200) contact Platform9 Support for MMIO window configuration
VM stuck at OVMF splash screen or fails POST
OVMF/QEMU version mismatch
Update OVMF package on the host
VM fails to boot, console shows UEFI error
hw_firmware_type=uefi set without hw_machine_type=q35
Set both properties together
GPU driver error in guest log: No NVIDIA GPU found
GPU not bound to vfio-pci on host
Re-run passthrough config; verify binding with lspci -k
vGPU VM fails to start on Ubuntu 24.04 host
vGPU not supported on Ubuntu 24.04 hosts currently
Use Ubuntu 22.04 for vGPU hosts
Related Pages
Set up GPU Passthrough — passthrough infrastructure setup
Set up vGPU — vGPU infrastructure setup
GPU Post-Upgrade Recovery — recover GPU VMs after host OS upgrades
GPU FAQs — migration behavior and other common questions
Last updated
Was this helpful?