PyTorch GPU Compute Capability and CUDA Version Compatibility Matrix: A Complete Guide

You can determine PyTorch GPU compatibility by matching your GPU's compute capability to the appropriate CUDA toolkit version using optional dependency groups in uv, which automatically resolves the correct wheel from the PyTorch index.

The PyTorch GPU compute capability and CUDA version compatibility matrix is essential knowledge when configuring deep learning environments. The baonguyen6742/uv-install-torch repository demonstrates a modern, reproducible approach to handling these dependencies using the uv package manager and explicit CUDA version tagging.

Understanding GPU Compute Capability and CUDA Versions

GPU compute capability refers to the version of the GPU hardware architecture, represented as a major.minor number (e.g., 8.6 for Ampere). NVIDIA assigns specific compute capabilities to each GPU generation, determining which CUDA toolkit versions can target that hardware.

The CUDA toolkit version (e.g., 12.4) provides the compiler and libraries for GPU acceleration. PyTorch releases pre-built binaries against specific CUDA versions, encoding this information in the wheel filename (e.g., torch-2.4.1+cu124).

How PyTorch Wheels Encode CUDA Compatibility

PyTorch uses local version identifiers to distinguish CUDA builds. In the pyproject.toml file of the repository, the [tool.uv.sources] section maps these extras to specific PyTorch indexes:

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "cpu" },
  { index = "pytorch-cu124", extra = "cu124" },
]

The +cu124 suffix in the wheel tag indicates compatibility with CUDA 12.4, which supports compute capabilities 5.0 through 9.0+. When you specify --extra cu124, uv queries the https://download.pytorch.org/whl/cu124 index and selects the wheel matching your Python version and platform.

Setting Up PyTorch with uv for Your GPU

Identifying Your GPU Compute Capability

Before installation, determine your hardware capabilities. The repository references NVIDIA's official documentation for GPU requirements. You can verify your specific GPU model using:

nvidia-smi

Then cross-reference your GPU architecture (e.g., Ampere, Ada Lovelace) with the compute capability version. For example, RTX 30-series cards typically have compute capability 8.6, while RTX 40-series have 8.9.

Matching Compute Capability to CUDA Version

Once you know your compute capability, select the appropriate CUDA toolkit:

• CUDA 11.8: Supports compute capability 3.5 through 9.0 (legacy support for older GPUs)
• CUDA 12.1/12.4: Supports compute capability 5.0 through 9.0+ (recommended for newer GPUs)

The baonguyen6742/uv-install-torch repository specifically demonstrates CUDA 12.4 support through the cu124 extra, which covers compute capabilities from Pascal (5.0) through Hopper (9.0).

Installing the Correct PyTorch Build

Use uv to synchronize dependencies with the appropriate extra flag. For a GPU supporting CUDA 12.4:

uv sync --extra cu124

This command reads the pyproject.toml optional dependency group:

[project.optional-dependencies]
cu124 = ["torch", "torchvision", "torchaudio"]

And resolves the packages from the pytorch-cu124 index defined in [tool.uv.sources].

Verifying Your Installation

After installation, confirm that PyTorch recognizes your GPU and matches the expected compute capability. The repository includes main.py to automate this verification:

import torch

print("torch version:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())

if torch.cuda.is_available():
    for i in range(torch.cuda.device_count()):
        props = torch.cuda.get_device_properties(i)
        print(f"Device {i}: {props.name}")
        print(f"  Compute Capability: {props.major}.{props.minor}")
        print(f"  Total Memory: {props.total_memory / 1e9:.2f} GB")

Run this with:

uv run main.py

Successful output shows the +cu124 suffix in the torch version and True for CUDA availability, confirming that the compute capability and CUDA version matrix has been correctly resolved.

Handling CPU-Only and Alternative CUDA Versions

If your GPU is not compatible with CUDA 12.4 or you lack a GPU entirely, switch to the CPU-only build:

uv sync --extra cpu

This uses the pytorch-cpu index and installs wheels without CUDA dependencies.

For older GPUs requiring earlier CUDA versions (e.g., CUDA 11.8), you would modify the pyproject.toml to add a new optional dependency group:

[project.optional-dependencies]
cu118 = ["torch", "torchvision", "torchaudio"]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "cpu" },
  { index = "pytorch-cu124", extra = "cu124" },
  { index = "pytorch-cu118", extra = "cu118" },
]

Then synchronize with uv sync --extra cu118.

If you encounter issues with cached wheels, clear the uv cache:

uv cache clean torch
uv sync --extra cu124

Summary

• GPU compute capability determines which CUDA toolkit versions your hardware supports, ranging from legacy 3.5 to modern 9.0+.
• PyTorch wheels encode CUDA compatibility using local version identifiers like +cu124, which correspond to specific compute capability ranges.
• The baonguyen6742/uv-install-torch repository demonstrates mapping compute capabilities to CUDA versions through pyproject.toml optional dependencies (cu124, cpu) and uv source indexes.
• Verification requires checking torch.cuda.is_available() and torch.cuda.get_device_properties() to confirm the correct compute capability is detected.
• Fallback options include CPU-only builds (--extra cpu) and clearing the uv cache when switching between CUDA versions.

Frequently Asked Questions

How do I check my GPU compute capability?

You can identify your GPU compute capability by running nvidia-smi to get your GPU model, then consulting NVIDIA's CUDA GPU support documentation to find the corresponding compute capability version (e.g., 8.6 for RTX 3090). Alternatively, after installing PyTorch, run torch.cuda.get_device_properties(0) to see the major and minor compute capability values directly from Python.

What CUDA version should I use for PyTorch?

Select the CUDA version that supports your GPU's compute capability while matching your NVIDIA driver version. For GPUs with compute capability 5.0 through 9.0+, CUDA 12.4 is recommended and demonstrated in the uv-install-torch repository. Older GPUs or drivers may require CUDA 11.8. Always verify that your driver supports the CUDA toolkit version you intend to use.

Can I install PyTorch with CUDA support using pip instead of uv?

Yes, you can install PyTorch with CUDA support using pip by specifying the index URL and CUDA version explicitly, such as pip install torch --index-url https://download.pytorch.org/whl/cu124. However, the uv approach shown in the baonguyen6742/uv-install-torch repository provides better reproducibility through locked dependencies in uv.lock and cleaner management of multiple CUDA versions via optional dependency groups in pyproject.toml.

Why does torch.cuda.is_available() return False after installation?

If torch.cuda.is_available() returns False, you likely installed the CPU-only build or a CUDA version incompatible with your driver or GPU compute capability. Verify that you used the correct extra flag (e.g., --extra cu124 instead of --extra cpu) and that your NVIDIA driver supports the CUDA toolkit version you selected. You may need to clear the uv cache with uv cache clean torch and resync, or upgrade your NVIDIA driver to support newer CUDA versions.

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