# Which CUDA Version Should I Use and How to Match It With Your NVIDIA Driver for Cosmos 3

> Find the right CUDA version for Cosmos 3 and NVIDIA drivers. Match PyTorch or vLLM CUDA builds to your driver using COSMOS3_UV_GROUP to avoid runtime failures.

- Repository: [NVIDIA Corporation/cosmos](https://github.com/NVIDIA/cosmos)
- Tags: how-to-guide
- Published: 2026-06-06

---

**Match your PyTorch or vLLM CUDA build to the CUDA version reported by `nvidia-smi` by setting `COSMOS3_UV_GROUP` to `cu130-train` for CUDA 13 drivers or `cu128-train` for CUDA 12.8 drivers to prevent GPU runtime failures.**

Cosmos 3, NVIDIA’s open-source generative AI framework for building physical AI systems, requires strict alignment between your NVIDIA driver’s CUDA capability and the CUDA-compiled wheels of PyTorch or vLLM. This guide explains exactly which CUDA version you should use based on your driver and how to configure the `COSMOS3_UV_GROUP` environment variable to pull the correct binaries.

## Check Your Driver’s CUDA Capability

Before installing dependencies, you must determine the CUDA version your driver supports. This value dictates which backend tag to use.

### Using nvidia-smi

Run the standard NVIDIA system management interface command and locate the "CUDA Version" in the top-right corner of the output:

```bash
nvidia-smi

```

Look for the line reporting `CUDA Version: 13` or `CUDA Version: 12.8`. This is the maximum CUDA runtime version your driver can support.

### Programmatic Detection

You can automate this check in Python when configuring deployment scripts:

```python
import subprocess, re

out = subprocess.check_output(["nvidia-smi"], encoding="utf-8")
match = re.search(r"CUDA Version:\s+(\d+\.\d+)", out)
driver_cuda = match.group(1) if match else "unknown"
print("Driver CUDA version:", driver_cuda)

```

This regex extracts the version string (e.g., "13.0" or "12.8") for conditional logic in your setup pipeline.

## Select the Correct Backend Tag

Cosmos 3 uses the `COSMOS3_UV_GROUP` environment variable to select CUDA-specific wheel indexes. Map your driver output to the correct tag:

- **Driver CUDA 13** (recommended): Set `COSMOS3_UV_GROUP=cu130-train`
- **Driver CUDA 12.8** (or any 12.x): Set `COSMOS3_UV_GROUP=cu128-train`

If your driver reports CUDA 13, use the default `cu130-train` group. For CUDA 12.8 or earlier 12.x versions, you must explicitly export the 12.8 group before installing. According to the troubleshooting section in [[`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md)](https://github.com/NVIDIA/cosmos/blob/main/README.md#which-cuda-version-should-i-use), installing a wheel built for a newer CUDA than the driver supports—such as `cu130` on a CUDA 12.x driver—causes `torch.cuda.is_available()` to return `False` and triggers the runtime error *“The NVIDIA driver on your system is too old.”*

## Install Cosmos 3 With the Matching CUDA Build

Once you have identified the correct tag, install the dependencies using `uv` or `pip` with the `--torch-backend` flag pointing to your specific group.

### Diffusers-Based Setup

For standard diffusion model training or inference using Diffusers, configure your environment and install as follows:

```shell

# Example for a CUDA 12.8 driver:

export COSMOS3_UV_GROUP=cu128-train

uv venv --python 3.13 --seed --managed-python
source .venv/bin/activate
uv pip install --torch-backend=${COSMOS3_UV_GROUP} \
    "diffusers @ git+https://github.com/huggingface/diffusers.git" \
    torch torchvision transformers

```

For CUDA 13 drivers, omit the export or explicitly set `export COSMOS3_UV_GROUP=cu130-train`.

### vLLM-Omni Setup

When deploying multimodal models with vLLM-Omni, specify the backend directly in the install command:

```shell

# For CUDA 13 drivers:

uv pip install --torch-backend=cu130 \
    "vllm-omni @ git+https://github.com/vllm-project/vllm-omni.git@main"

# For CUDA 12.8 drivers:

uv pip install --torch-backend=cu128 \
    "vllm-omni @ git+https://github.com/vllm-project/vllm-omni.git@main"

```

As documented in [[`cookbooks/cosmos3/README.md`](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md)](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md#cuda-driver-and-the-cuxxx-backend), this variable ensures `uv` pulls wheels compiled against the specific CUDA runtime your driver supports.

## Verify Your CUDA Configuration

After installation, run a quick sanity check to confirm PyTorch recognizes your GPU:

```python
import torch
print("Torch CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())

```

The value of `torch.version.cuda` must match your driver-reported version (e.g., `13.0` for driver CUDA 13, or `12.8` for driver CUDA 12.8). If `torch.cuda.is_available()` returns `False`, your backend tag likely exceeds your driver capability. The notebook [`cookbooks/cosmos3/reasoner/run_with_cosmos_framework.ipynb`](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/reasoner/run_with_cosmos_framework.ipynb) demonstrates this validation step in a Jupyter environment.

## Summary

- **Always check** `nvidia-smi` first to find your driver’s CUDA version before installing Cosmos 3.
- **Set `COSMOS3_UV_GROUP`** to `cu130-train` for CUDA 13 drivers or `cu128-train` for CUDA 12.8/12.x drivers.
- **Use `--torch-backend`** with `uv pip install` to force the correct CUDA-compiled wheels for PyTorch and vLLM.
- **Validate** with `torch.version.cuda` and `torch.cuda.is_available()` to ensure GPU acceleration is active.
- **Avoid mixing versions**: A `cu130` wheel on a CUDA 12.x driver will silently fall back to CPU or fail with a driver version error.

## Frequently Asked Questions

### What happens if I install the wrong CUDA version for Cosmos 3?

Installing a wheel compiled for a newer CUDA version than your driver supports—such as using `cu130-train` on a system with a CUDA 12.8 driver—causes PyTorch to fail GPU initialization. You will see `torch.cuda.is_available()` return `False` and encounter the runtime error message *“The NVIDIA driver on your system is too old”* when attempting to run inference.

### Can I use CUDA 12.6 or 12.4 with Cosmos 3?

According to the source documentation in [[`cookbooks/cosmos3/README.md`](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md)](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md#cuda-driver-and-the-cuxxx-backend), you should use the `cu128-train` group for any CUDA 12.x driver, including 12.8, 12.6, or 12.4. The `cu128` wheels are built to be compatible with the entire CUDA 12.x series, though CUDA 12.8 is the specific target version listed in the official mapping table.

### Where does Cosmos 3 define the CUDA backend requirements?

The primary documentation resides in [[`README.md`](https://github.com/NVIDIA/cosmos/blob/main/README.md)](https://github.com/NVIDIA/cosmos/blob/main/README.md#which-cuda-version-should-i-use) under the troubleshooting section, with additional context in [[`cookbooks/cosmos3/README.md`](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md)](https://github.com/NVIDIA/cosmos/blob/main/cookbooks/cosmos3/README.md#cuda-driver-and-the-cuxxx-backend). The [[`inference_benchmarks.md`](https://github.com/NVIDIA/cosmos/blob/main/inference_benchmarks.md)](https://github.com/NVIDIA/cosmos/blob/main/inference_benchmarks.md) file also assumes this correct driver-CUDA pairing for reproducing reported performance numbers.

### Is Python 3.13 required for Cosmos 3 compatibility?

The installation examples in the repository, particularly in the cookbooks, specify Python 3.13 when creating the virtual environment with `uv venv --python 3.13`. While the core Cosmos 3 logic may function on other Python versions, the official supported path and tested configurations use Python 3.13 alongside the specified CUDA backend tags.