uv.lock

Overview

The uv.lock file is a dependency lock file used by the Python packaging ecosystem, particularly in conjunction with the uv tool or similar Python package managers. Its main purpose is to lock down exact versions of dependencies and their sources for a Python project, ensuring reproducible builds and consistent environments across different machines and deployments.

This file specifies:

• The version and revision of the lock file format.

• The required Python version compatibility range.

• A detailed list of all packages (both direct and transitive dependencies), including:

  • Package name and exact version.

  • Source information (registry URLs or virtual source).

  • Download URLs for source distributions and wheels.

  • SHA256 hashes for integrity verification.

  • Any dependencies or markers relevant for conditional installation.

• Metadata about development dependencies and version constraints.

Such a lock file guarantees that the environment setup is deterministic, reducing "works on my machine" issues and helping with auditing dependency chains.

Detailed Explanation

File Structure and Key Sections

The file is written in a format similar to TOML, structured into tables and arrays with the following key sections:

Top Level Fields

• version (integer):
  The lock file format version. Here, it is 1.

• revision (integer):
  Revision number of the lock file, typically incremented when the file is updated without changing the version format. Here, it is 1.

• requires-python (string):
  Specifies the Python versions compatible with this lock file. For example:

  ">=3.10, <3.13"
  

  means Python versions starting from 3.10 up to but not including 3.13.

[[package]] Tables

Each [[package]] section describes a single Python package included in the dependency graph. These entries contain:

• name (string): The package name, e.g., "attrs".

• version (string): The exact package version locked, e.g., "25.3.0".

• source (table):

  • registry (string): The URL of the package index (mirror) from which the package is fetched.

  • Or virtual (string): Indicates a virtual/local source, e.g., "." for the local project.

• dependencies (optional array):
  Lists other packages this package depends on, possibly with environment markers.
  Example:

  dependencies = [
      { name = "attrs" },
      { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
  ]
  

• sdist (table):
  URL and hash for the source distribution (tarball).

  • url (string): The download URL.

  • hash (string): SHA256 checksum for integrity verification.

• wheels (array):
  Lists available wheel files for various platforms and Python versions, each with a URL and hash.
  Example:

  wheels = [
      { url = "https://mirrors.aliyun.com/pypi/packages/...", hash = "sha256:..." },
      ...
  ]
  

[package.dev-dependencies] Table

Defines development-only dependencies grouped by purpose, e.g., test. These are packages required during development and testing but not in production.

Example:

[package.dev-dependencies]
test = [
    { name = "hypothesis" },
    { name = "openpyxl" },
    ...
]

[package.metadata] Table

Metadata about the locked packages, including:

• requires-dist (array):
  Specifies runtime dependencies with version specifiers.

• requires-dev (table):
  Specifies development dependencies with version specifiers.

Usage and Interaction with the System

• Dependency Resolution: The lock file is generated after resolving the dependency graph of the project’s declared requirements, including transitive dependencies.

• Environment Reproducibility: When installing packages, the package manager uses uv.lock to install exact versions with verified sources, ensuring consistent environments.

• Security and Integrity: The SHA256 hashes for sdist and wheels enable verification of downloaded packages, protecting against tampering.

• Development vs. Production: The file distinguishes between production dependencies and development-only dependencies to optimize deployment environments.

• Source Mirroring: The URLs point to mirrored registries (mirrors.aliyun.com), showing usage of a specific PyPI mirror for faster or localized package access.

Important Implementation Details

• No Classes or Functions: This file is declarative and contains no executable code, classes, or functions.

• Precise Version Pinning: Each package version is pinned precisely, avoiding floating versions.

• Multiple Wheels per Package: For each package, multiple wheel variants are listed for different architectures and Python versions, enabling platform-appropriate installation.

• Conditional Dependencies: Some dependencies are included only under certain conditions (e.g., Python version), allowing environment-specific optimization.

• Virtual Source: The local project itself is listed as a package with source { virtual = "." }, indicating local source code.

Example Excerpt Interpretation

For the package attrs:

[[package]]
name = "attrs"
version = "25.3.0"
source = { registry = "https://mirrors.aliyun.com/pypi/simple" }
sdist = { url = "...attrs-25.3.0.tar.gz", hash = "sha256:..." }
wheels = [
    { url = "...attrs-25.3.0-py3-none-any.whl", hash = "sha256:..." },
]

• The project depends on attrs version 25.3.0.

• The package is fetched from the Aliyun PyPI mirror.

• Both source distribution and wheel are available.

• Integrity is verified by SHA256 checksums.

How This File Interacts With Other Project Files

• Project Manifest (pyproject.toml / requirements.txt / uv.yaml):
  The lock file is generated based on declared dependencies in these files.

• Package Manager (uv or similar):
  Reads this lock file to install exact packages.

• Virtual Environments:
  Ensures reproducible environments by providing an immutable dependency snapshot.

• CI/CD Pipelines and Deployment Systems:
  Use this lock file to replicate consistent environments.

Mermaid Diagram: Dependency Flowchart

This flowchart illustrates the main conceptual flow of dependency resolution and usage related to the uv.lock file:

flowchart TD
    A[Project Manifest] --> B[Dependency Resolver]
    B --> C[uv.lock File]
    C --> D[Package Installer]
    D --> E[Virtual Environment / Deployment]
    C --> F[Hash Verification]
    F --> D
    E --> G[Application Runtime]

    style C fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:1px

• Project Manifest: User-defined dependencies in pyproject.toml or similar.

• Dependency Resolver: Computes full dependency graph and pins versions.

• uv.lock File: Stores locked versions and sources.

• Hash Verification: Ensures package integrity during installation.

• Package Installer: Installs packages based on lock file.

• Virtual Environment / Deployment: Isolated environment setup.

• Application Runtime: Final environment where the app runs.

Summary

• uv.lock is a lock file for Python dependencies ensuring reproducible installs.

• It contains exact versions, sources, and hashes for all packages.

• It distinguishes between runtime and development dependencies.

• It is a non-executable, declarative file critical for environment consistency.

• Works with package managers and environment tools to provide deterministic builds.

This file is essential for dependency management, security, and consistent deployment in Python projects using the uv ecosystem or compatible tools.