What is uv.lock

Last updated: April 1, 2026

Quick Answer: A uv.lock file is a dependency lock file used by the uv Python package manager to record the exact versions of all project dependencies and their sub-dependencies for reproducible installs across different environments.

Key Facts

Overview

The uv.lock file is a critical component of the uv Python package manager ecosystem. When you work with uv to manage your project's dependencies, it automatically generates and maintains a lock file that records the exact versions of every package and sub-dependency used in your project. This ensures reproducibility and consistency across development, testing, and production environments.

Purpose and Function

The primary purpose of uv.lock is to provide dependency lock files for Python projects. When you install packages using uv, it resolves all dependencies and creates a lock file that captures the exact versions. This means that anyone else working on the project, or any deployment system, will install the exact same versions of all packages, preventing the "it works on my machine" problem that plagued Python development for years.

How It Works

When you run uv sync or uv install, the tool:

Advantages

Using uv.lock provides several benefits compared to unpinned dependencies. It ensures reproducible builds, prevents unexpected breaking changes from new package versions, and allows development teams to work with confidence that their code will run identically across all environments. The uv package manager itself is significantly faster than traditional pip, making the entire dependency management process more efficient.

Similarity to Other Lock Files

Developers familiar with other package managers will recognize uv.lock as similar to Node.js's package-lock.json or Python's poetry.lock file. Each serves the same purpose: recording exact dependency versions for reproducibility. The uv.lock format is specifically optimized for the uv package manager's performance characteristics.

Related Questions

What is the difference between uv and pip?

uv is a faster Python package manager written in Rust that serves as a modern alternative to pip. While pip is the traditional Python package manager, uv provides superior performance and better dependency resolution while maintaining similar functionality.

How do I use a uv.lock file in my project?

The uv.lock file is automatically managed by the uv package manager. Simply run uv sync or uv install to generate and use the lock file. Commit it to version control alongside your project code to ensure all team members use identical dependencies.

Should I commit uv.lock to version control?

Yes, you should commit uv.lock to your version control system. This ensures all developers and CI/CD systems use the exact same dependency versions, maintaining consistency and reproducibility across your entire project.

Sources

  1. uv - The Fast Python Package Manager MIT
  2. GitHub - uv Package Manager MIT