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

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:

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:

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

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

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

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 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#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#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#cuda-driver-and-the-cuxxx-backend). The [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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}