# uv.lock File Role in Reproducible PyTorch GPU Installations: A Complete Guide

> Discover the crucial role of the uv.lock file in achieving reproducible PyTorch GPU installations. Ensure deterministic builds with precise CUDA wheel pinning.

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

---

**The `uv.lock` file freezes the entire dependency tree—including platform-specific CUDA wheels and their exact hashes—to guarantee deterministic PyTorch GPU installations across development machines, CI pipelines, and containers.**

Managing PyTorch GPU dependencies traditionally involves navigating complex manual specifications for CUDA versions and operating system compatibility. The `uv.lock` file in the **baonguyen6742/uv-install-torch** repository demonstrates how the uv package manager creates deterministic environments that eliminate "works on my machine" issues when installing PyTorch with GPU support.

## Exact Version Pinning for CUDA-Specific Wheels

The `uv.lock` file serves as the single source of truth for reproducible PyTorch installations. Unlike traditional [`requirements.txt`](https://github.com/baonguyen6742/uv-install-torch/blob/main/requirements.txt) files that might specify loose version constraints, the lock file captures **exactly** which wheels were resolved during the initial `uv lock` command.

In the context of GPU-accelerated PyTorch, this precision is critical because PyTorch distributes separate binaries for each combination of Python version, operating system, and CUDA toolkit version. The lock file stores the precise URLs and checksums for wheels like `torch==2.4.1+cu124`, ensuring that every environment rebuild retrieves identical artifacts without drift from newly published releases.

## Platform-Specific Resolution Markers

A key feature of `uv.lock` is its use of **resolution-markers** that encode platform-specific logic directly into the dependency graph. Examining lines 4-31 of the [`uv.lock`](https://github.com/baonguyen6742/uv-install-torch/blob/master/uv.lock) file reveals conditions such as:

```toml
extra == "extra-16-uv-install-torch-cu124"
sys_platform == "linux"
python_full_version >= "3.11"

```

These markers tell uv exactly which wheel to select based on the runtime environment. When you run `uv sync --extra cu124` on a Linux machine with Python 3.11 or higher, uv reads these markers and installs the CUDA 12.4-compatible wheels. On macOS or Windows, the resolver selects the appropriate platform-specific binaries recorded in the same lock file, ensuring cross-platform consistency without manual intervention.

## Extra-Based CUDA Selection in pyproject.toml

The project defines optional dependencies as **extras** within [[`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml)](https://github.com/baonguyen6742/uv-install-torch/blob/master/pyproject.toml), specifically `cpu` and `cu124`. The `uv.lock` file maintains separate, complete dependency graphs for each extra:

- **`cu124`**: Resolves to GPU-enabled `torch`, `torchvision`, and `torchaudio` wheels containing the `+cu124` local version tag
- **`cpu`**: Resolves to CPU-only variants without CUDA dependencies

This design allows the same lock file to support both development scenarios. Running `uv sync --extra cu124` installs the GPU-accelerated stack tested on the repository's RTX 3060 + CUDA 12.4 system, while `uv sync --extra cpu` installs the lighter CPU-only variant for machines without NVIDIA hardware.

## Generating the Lock File

To create a reproducible environment for PyTorch GPU development, generate the lock file once with your desired extra:

```bash

# Install uv if not already present

pip install uv

# Generate uv.lock with CUDA 12.4-specific resolutions

uv lock --extra cu124

```

This command resolves the dependency graph defined in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml), downloads the metadata for all required packages, selects the platform-specific wheels that satisfy the CUDA 12.4 constraint, and writes the complete resolution to `uv.lock`. Commit this file to version control to share the exact environment definition with collaborators.

## Reproducing the Environment

Any machine with uv installed can recreate the identical environment by executing:

```bash

# Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install exact versions from lock file

uv sync --extra cu124

```

During this process, uv performs three critical validation steps:
1. Reads the locked dependency graph from `uv.lock`
2. Verifies the SHA-256 hashes of all cached or downloaded wheels
3. Installs `torch==2.4.1+cu124` and its dependencies into the active virtual environment

Because the lock file contains the exact URLs and hashes, uv bypasses the resolution phase entirely, making the installation both faster and deterministic.

## Verifying GPU Installation

After synchronization, verify that PyTorch correctly detects your GPU using the verification logic found in [[`main.py`](https://github.com/baonguyen6742/uv-install-torch/blob/main/main.py)](https://github.com/baonguyen6742/uv-install-torch/blob/master/main.py):

```python
import torch
import torchvision
import torchaudio

print("torch version:", torch.__version__)          

# Output: 2.4.1+cu124

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

# Output: True (on compatible GPU)

print("GPU name:", torch.cuda.get_device_name(0))   

# Output: NVIDIA GeForce RTX 3060 (or your GPU model)

```

This script confirms that the environment matches the locked specification, including the CUDA runtime version compiled into the PyTorch binaries.

## Switching Between CPU and GPU Modes

The lock file supports seamless switching between hardware configurations without regenerating the lock. To install CPU-only PyTorch wheels—which exclude CUDA libraries and reduce installation size—run:

```bash
uv sync --extra cpu

```

The resolver consults the `cpu` extra section of `uv.lock` and installs the standard PyTorch wheels without the `+cu124` suffix. This eliminates CUDA-related packages entirely, making it ideal for deployment environments or development machines without NVIDIA drivers.

## Cache Efficiency and CI/CD Integration

Because `uv.lock` contains complete distribution metadata, uv can aggressively cache packages without risking version drift. When running `uv cache prune`, the manager respects the locked hashes and never removes versions referenced in the lock file. In CI/CD pipelines, checking out the repository and running `uv sync --extra cu124` reproduces the exact environment originally validated on the development workstation, ensuring that tests run against identical PyTorch and CUDA library versions.

## Summary

- The `uv.lock` file pins exact versions and hashes for all dependencies, including platform-specific PyTorch CUDA wheels.
- **Resolution-markers** in the lock file encode conditions for selecting the correct wheels based on operating system, Python version, and selected extras.
- The `cu124` extra in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) triggers installation of GPU-enabled `torch==2.4.1+cu124`, while the `cpu` extra installs CPU-only variants.
- Running `uv sync --extra cu124` reads the lock file and reproduces the environment without re-resolving dependencies, ensuring deterministic builds across machines.
- The combination of `uv.lock` and extras eliminates manual CUDA version management and prevents "works on my machine" deployment failures.

## Frequently Asked Questions

### Does uv.lock work across different operating systems?

Yes, the lock file stores platform-specific markers for all supported operating systems. When you run `uv sync` on Linux, macOS, or Windows, uv evaluates the markers in `uv.lock` and selects the appropriate wheels for that platform. However, GPU extras like `cu124` require compatible NVIDIA drivers and CUDA runtime on the target machine to function correctly.

### How do I upgrade PyTorch to a newer CUDA version?

Modify the dependency specification in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) to reference the desired torch version with the appropriate CUDA tag (e.g., `cu126` for CUDA 12.6), then regenerate the lock file with `uv lock --extra cu124`. This updates `uv.lock` with new URLs and hashes for the updated wheels. Commit the changed lock file to version control to propagate the update to your team.

### Can I use the same uv.lock for both CPU and GPU installations?

Yes, the lock file simultaneously stores the complete dependency graphs for all extras defined in [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml). You can run `uv sync --extra cpu` on a laptop without a GPU and `uv sync --extra cu124` on a workstation with an NVIDIA card, both using the same committed `uv.lock` file. Each command installs the correct wheel variant without conflicts.

### What happens if my CUDA driver version is older than 12.4?

The installation will complete successfully because the lock file ensures you receive `torch==2.4.1+cu124`, but `torch.cuda.is_available()` will return `False` at runtime if your driver is incompatible. You must either upgrade your NVIDIA driver to support CUDA 12.4 or regenerate the lock file with a PyTorch version built for your specific CUDA version by updating [`pyproject.toml`](https://github.com/baonguyen6742/uv-install-torch/blob/main/pyproject.toml) and running `uv lock` again.