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

> Streamline PyTorch GPU support in CI/CD. Integrate uv sync with optional extras for deterministic CUDA workflows using a single command. Automate your GPU builds efficiently.

- Repository: [Th3Unknovvn/uv-install-torch](https://github.com/baonguyen6742/uv-install-torch)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Use uv's optional extras and explicit indexes in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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:

```bash
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:

```bash
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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml).

### Verification Smoke Tests

The repository includes [`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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:

```bash
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:

```bash
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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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`](https://github.com/baonguyen6742/uv-install-torch/blob/main/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.