> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/gpu/gpu-support-pcd/gpu-vm-compatibility.md).

# 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

<code class="expression">space.vars.product\_name</code> 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:

```bash
pcdctl image set <IMAGE_ID> hw_machine_type=q35
```

Confirm the property is set:

```bash
pcdctl image show <IMAGE_ID> | grep hw_machine_type
```

## UEFI/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:

```bash
pcdctl image set <IMAGE_ID> hw_firmware_type=uefi
```

{% hint style="info" %}
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.
{% endhint %}

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

| Host OS                   | Passthrough | vGPU          |
| ------------------------- | ----------- | ------------- |
| 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:

```
BdsDxe: failed to load Boot0001 "UEFI QEMU DVD-ROM"
```

or gets stuck at the OVMF splash screen, the OVMF version and QEMU version on the host may be mismatched. Update the OVMF package:

```bash
sudo apt-get update && sudo apt-get install --only-upgrade ovmf
```

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:

```bash
pcdctl image show <IMAGE_ID> | grep -E "hw_machine_type|hw_firmware_type"
```

| Property           | Required value for GPU VMs                                        |
| ------------------ | ----------------------------------------------------------------- |
| `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:

```bash
# Confirm IOMMU is enabled and groups are populated
ls /sys/kernel/iommu_groups/ | wc -l   # should be > 0

# Confirm the GPU PCI device exists and the driver is correct (passthrough)
lspci -k | grep -A 3 "NVIDIA"          # should show vfio-pci for passthrough hosts

# Confirm NVIDIA vGPU manager is running (vGPU hosts)
systemctl status nvidia-vgpu-mgr       # should show active (running)
```

### 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:

```bash
libvirtd --version
qemu-system-x86_64 --version
uname -r
```

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](/private-cloud-director/gpu/gpu-support-pcd/gpu-faqs.md) for migration behavior details.

## Common Boot Failures and Resolutions

| Symptom                                               | Likely Cause                                                             | Resolution                                                                                                        |
| ----------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| 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](/private-cloud-director/gpu/gpu-support-pcd/set-up-gpu-passthrough.md) — passthrough infrastructure setup
* [Set up vGPU](/private-cloud-director/gpu/gpu-support-pcd/setup-vgpu.md) — vGPU infrastructure setup
* [GPU Post-Upgrade Recovery](/private-cloud-director/gpu/gpu-support-pcd/gpu-post-upgrade-recovery.md) — recover GPU VMs after host OS upgrades
* [GPU FAQs](/private-cloud-director/gpu/gpu-support-pcd/gpu-faqs.md) — migration behavior and other common questions


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/gpu/gpu-support-pcd/gpu-vm-compatibility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.