incus-mirror/doc/reference/devices_gpu.md

(devices-gpu)=

Type: gpu

GPU devices make the specified GPU device or devices appear in the instance.

For containers, a `gpu` device may match multiple GPUs at once.
For VMs, each device can match only a single GPU.

The following types of GPUs can be added using the gputype device option:

• physical (container and VM): Passes an entire GPU through into the instance. This value is the default if gputype is unspecified.
• mdev (VM only): Creates and passes a virtual GPU through into the instance.
• mig (container only): Creates and passes a MIG (Multi-Instance GPU) through into the instance.
• sriov (VM only): Passes a virtual function of an SR-IOV-enabled GPU into the instance.
• native-context (VM only): Gives the VM GPU acceleration through virtio-gpu DRM native context, without passing the GPU through.

The available device options depend on the GPU type and are listed in the tables in the following sections.

(gpu-physical)=

gputype: physical

The `physical` GPU type is supported for both containers and VMs.
It supports hotplugging only for containers, not for VMs.

A physical GPU device passes an entire GPU through into the instance.

Device options

GPU devices of type physical have the following device options:

% Include content from config_options.txt

    :start-after: <!-- config group devices-gpu_physical start -->
    :end-before: <!-- config group devices-gpu_physical end -->

(gpu-mdev)=

gputype: mdev

The `mdev` GPU type is supported only for VMs.
It does not support hotplugging.

An mdev GPU device creates and passes a virtual GPU through into the instance. You can check the list of available mdev profiles by running incus info --resources.

Device options

GPU devices of type mdev have the following device options:

% Include content from config_options.txt

    :start-after: <!-- config group devices-gpu_mdev start -->
    :end-before: <!-- config group devices-gpu_mdev end -->

(gpu-mig)=

gputype: mig

The `mig` GPU type is supported only for containers.
It does not support hotplugging.

A mig GPU device creates and passes a MIG compute instance through into the instance. Currently, this requires NVIDIA MIG instances to be pre-created.

Device options

GPU devices of type mig have the following device options:

% Include content from config_options.txt

    :start-after: <!-- config group devices-gpu_mig start -->
    :end-before: <!-- config group devices-gpu_mig end -->

You must set either mig.uuid (NVIDIA drivers 470+) or both mig.ci and mig.gi (old NVIDIA drivers).

(gpu-sriov)=

gputype: sriov

The `sriov` GPU type is supported only for VMs.
It does not support hotplugging.

An sriov GPU device passes a virtual function of an SR-IOV-enabled GPU into the instance.

Device options

GPU devices of type sriov have the following device options:

% Include content from config_options.txt

    :start-after: <!-- config group devices-gpu_sriov start -->
    :end-before: <!-- config group devices-gpu_sriov end -->

(gpu-native-context)=

gputype: native-context

The `native-context` GPU type is supported only for VMs.
It does not support hotplugging.

A native-context GPU device gives the VM GPU acceleration through virtio-gpu DRM native context. The host GPU is not passed through or rebound to vfio-pci; it stays owned by the host and is shared with the guest, so the host can keep using it at the same time.

This requires QEMU 11.0.0 or newer and virglrenderer on the host built with DRM native context support. DRM native context was introduced in virglrenderer 1.0.0, but the version needed in practice depends on the GPU and kernel (for example, AMD support became usable around 1.1 and Intel around 1.3). It also needs a host GPU and guest driver that support DRM native context, and a guest with a matching virtio-gpu DRM driver.

The selector options below are optional. If a GPU is selected, its DRM render node is used as the render node for the QEMU egl-headless display. If no GPU is selected, QEMU uses its default render node.

Device options

GPU devices of type native-context have the following device options:

% Include content from config_options.txt

    :start-after: <!-- config group devices-gpu_native_context start -->
    :end-before: <!-- config group devices-gpu_native_context end -->