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

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 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 file reveals conditions such as:

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

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

# 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/master/main.py):

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:

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 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 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. 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 and running uv lock again.

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