GPU and CUDA Setup
This guide shows how to set up an NVIDIA GPU on TunaOS. It covers image choice, driver checks, and CUDA workloads in containers.
Choose an image
The -nvidia flavor has NVIDIA drivers and CUDA. Use it for AI, graphics, and VFX work.
| Flavor | Meaning |
|---|---|
-nvidia | NVIDIA drivers and CUDA |
-nvidia-hwe | NVIDIA and CUDA on the HWE kernel |
Example image names:
ghcr.io/tuna-os/albacore:gnome-nvidiaghcr.io/tuna-os/yellowfin:gnome-nvidia-hwe
Not every variant publishes an -nvidia flavor. Check the page of your variant, such as Albacore, before you switch. See Variant guide for the full list.
Other variants use open-source drivers. This guide does not cover them.
Switch to an NVIDIA image
Use bootc switch, then reboot:
sudo bootc switch ghcr.io/tuna-os/albacore:gnome-nvidia
systemctl reboot
If the new image causes a problem, run sudo bootc rollback and reboot. See Rollback.
The image sets kernel arguments to block nouveau and to enable nvidia-drm.modeset=1. See Layers for how these arguments work.
Check the driver
After the reboot, run:
nvidia-smi
The output lists your GPU, the driver version, and the CUDA version that the driver supports.
To check that the kernel loads the module:
lsmod | grep nvidia
Run CUDA workloads in containers
Do not install the CUDA toolkit on the host. The host is immutable. Run your tools in a container instead.
Use Podman with the Container Device Interface (CDI):
podman run --rm --device nvidia.com/gpu=all \
docker.io/nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
Pick a CUDA image tag that matches the CUDA version in the nvidia-smi output or older.
For a long-lived setup, use a toolbox or Distrobox container. See the AI development quickstart for more.
The CDI spec file must exist for --device nvidia.com/gpu=all to work. This guide does not confirm where TunaOS creates it. If the command fails with an unknown device error, see the section on problems.
Hardware notes
- System requirements lists a GTX 1060 or newer, with 8 GB or more of VRAM for AI work.
- This guide does not document which GPU generations the driver supports. Check the release notes of the NVIDIA driver.
- This guide does not document Secure Boot with the NVIDIA modules. See Secure Boot.
Troubleshooting
nvidia-smi says it cannot talk to the driver. Confirm you booted the -nvidia image with bootc status. Then reboot. If Secure Boot is on, check whether it blocks the module.
Black screen or no display after the switch. Run sudo bootc rollback and reboot. Then open an issue with your GPU model and the output of bootc status.
Podman cannot find nvidia.com/gpu. The CDI spec is missing. Run ls /etc/cdi /var/run/cdi. If both are empty, open an issue.
The container says the CUDA version is too new. Use a CUDA image tag that is not newer than the CUDA version shown by nvidia-smi.
Report a problem
Open an issue in the TunaOS repository. Include the image name, GPU model, and nvidia-smi output.