CI/CD Integration of uv Sync for PyTorch GPU Support Workflows: A Complete Guide

Use uv's optional extras and explicit indexes in pyproject.toml to install CUDA-specific PyTorch wheels with a single uv sync --extra cu124 command, enabling deterministic GPU workflows in CI/CD pipelines.

The baonguyen6742/uv-install-torch repository demonstrates a production-ready approach to CI/CD integration of uv sync for PyTorch GPU support workflows. By leveraging uv's fast dependency resolution and lockfile generation, this configuration eliminates manual index management while ensuring reproducible PyTorch installations across Linux CI runners. The setup encodes CUDA-specific wheels as optional dependencies, allowing pipelines to switch seamlessly between CPU and GPU builds without modifying application code.

Repository Architecture and Configuration Files

Centralized Configuration in pyproject.toml

The pyproject.toml file serves as the single source of truth for the entire installation process. According to the repository source code, this file declares required runtime libraries and defines optional extras for both CPU (cpu) and CUDA 12.4 (cu124) builds. The tool.uv.sources section maps the torch, torchvision, and torchaudio packages to PyTorch's official wheel indexes, enabling uv to resolve the correct binaries at install time.

Explicit Index Management for CUDA Wheels

Within pyproject.toml, the tool.uv.index blocks define two explicit indexes: https://download.pytorch.org/whl/cpu for CPU-only wheels and the corresponding pytorch-cu124 index for GPU support. Marking these indexes as explicit = true ensures uv only queries them for the specific packages listed in tool.uv.sources, preventing index pollution during dependency resolution. This isolation is critical for CI environments where conflicting package sources might otherwise cause resolution failures.

Conflict Prevention Between Hardware Variants

The configuration includes a tool.uv.conflicts section that guarantees mutual exclusivity between the cpu and cu124 extras. This safety mechanism prevents contradictory installations where both CPU and GPU wheels might otherwise attempt to satisfy the same dependency, ensuring deterministic behavior in automated pipelines.

Implementing CI/CD Pipelines with uv Sync

GPU-Enabled Installation Steps

To install PyTorch with GPU support in a CI job, execute:

uv sync --extra cu124

This command instructs uv to select the CUDA 12.4 index, resolve the GPU-specific wheel versions, and generate a deterministic uv.lock file. The process completes significantly faster than traditional pip installations due to uv's Rust-based resolver, making it ideal for time-sensitive CI workflows.

CPU-Only Fallback Builds

For runners without GPU access or testing environments requiring CPU emulation, switch to CPU wheels using:

uv sync --extra cpu

The same codebase supports both hardware targets without modification, enabling matrix builds that validate functionality across different compute configurations using a single pyproject.toml.

Verification Smoke Tests

The repository includes main.py as a minimal verification script that validates the installation environment. Integrate this into CI pipelines to confirm CUDA visibility before running test suites:

uv run main.py

This executes a GPU tensor operation and outputs diagnostic information, including torch.__version__ (e.g., 2.4.1+cu124), torch.cuda.is_available() status, and NVIDIA device properties. Typical successful output includes:

torch.__version__: 2.4.1+cu124
torch.cuda.is_available: True
Device 0 : _CudaDeviceProperties(name='NVIDIA GeForce RTX 3060', major=8, minor=6, total_memory=11931MB, ...)
tensor([[1, 2, 3],
        [2, 4, 6]], device='cuda:0')

Cache Optimization and Maintenance Strategies

Persistent Caching Across Builds

Because uv.lock captures exact wheel versions and hashes, CI systems can cache both the lockfile and uv's global cache directory between runs. This dramatically reduces build times for subsequent pipeline executions, as uv skips resolution and installation for unchanged dependencies.

Selective Cache Management

When troubleshooting installation issues or reclaiming disk space in long-running CI environments, use uv's targeted cache commands:

uv cache prune          # Remove unused cache entries

uv cache clean torch    # Target specific package caches

These commands prove particularly useful when switching between CUDA versions or when outdated wheels persist in the cache.

Summary

• Configure optional extras (cpu and cu124) in pyproject.toml to encode hardware-specific PyTorch wheels without duplicating dependency lists
• Use tool.uv.index with explicit = true to isolate PyTorch's separate CPU and CUDA repositories from the default package index
• Execute uv sync --extra cu124 for deterministic GPU installations or --extra cpu for CPU-only builds on the same codebase
• Leverage the generated uv.lock for reproducible builds and cache the lockfile between CI runs to accelerate pipeline execution
• Verify installations using main.py to confirm CUDA availability and correct wheel versions before running production test suites

Frequently Asked Questions

What is uv and why use it for PyTorch installations?

uv is a fast Python package manager written in Rust that replaces pip and virtualenv in modern workflows. For PyTorch GPU support workflows, uv resolves the complex index dependencies required for CUDA wheels significantly faster than pip while generating lockfiles that ensure bit-for-bit identical installations across development machines and CI environments.

How does the repository handle both CPU and GPU builds?

The repository defines mutually exclusive extras in pyproject.toml using tool.uv.conflicts. When you run uv sync --extra cu124, uv pulls from the PyTorch CUDA 12.4 index; with --extra cpu, it selects the CPU-only index at https://download.pytorch.org/whl/cpu. Both paths generate compatible lockfiles without requiring changes to application source code, enabling true matrix testing across hardware types.

Can I use this configuration with GitHub Actions or GitLab CI?

Yes. The static configuration in pyproject.toml works with any CI platform supporting Linux runners and NVIDIA GPUs. Install uv in your pipeline job, cache the .venv directory and uv.lock file between runs, and execute uv sync --extra cu124 followed by uv run to execute tests. The explicit index configuration ensures consistent behavior regardless of the CI provider's default Python environment.

How do I troubleshoot CUDA version mismatches in CI?

Check the output of uv run main.py to verify torch.cuda.is_available() returns True and inspect torch.__version__ for the correct CUDA suffix (e.g., +cu124). If mismatches occur, ensure your CI runner's NVIDIA driver supports CUDA 12.4, and clear the uv cache using uv cache clean torch to force fresh wheel downloads from the correct index.

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