hatch-uv-lock

Hatchling build hook that embeds the project's uv.lock and pyproject.toml into its wheels. A tool like uvrev tool run can then rebuild the exact locked environment from the wheel alone, with uv sync --locked --no-install-project.

Usage

[project]
name = "my-project"

[build-system]
requires = ["hatchling>=1.28", "hatch-uv-lock"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.uv-lock]

The hook is active whenever hatchling loads it, so the (empty) [tool.hatch.build.hooks.uv-lock] table is all it takes. There is no other switch. To use it for wheels only, use [tool.hatch.build.targets.wheel.hooks.uv-lock] instead (the sdist then does not force-include uv.lock).

hatchling's generic build hook options work as usual. For example, enable-by-default = false turns the hook off unless HATCH_BUILD_HOOKS_ENABLE=true is set.

Using it from an existing build hook

from pathlib import Path

from hatch_uv_lock import add_lock_files


class MyBuildHook(BuildHookInterface):
    def initialize(self, version, build_data):
        add_lock_files(
            root=Path(self.root),
            target_name=self.target_name,
            version=version,
            dynamic=self.metadata.dynamic,
            build_data=build_data,
        )

self.metadata.dynamic is the original project.dynamic list (hatchling keeps a copy before metadata hooks change it).

What ends up where

Reading the files from an installed distribution:

from importlib.metadata import distribution

lock = distribution("my-project").read_text("extra_metadata/uv.lock")

Checks

The lock file itself is not checked. The only check: project.dynamic must not contain dependencies or optional-dependencies. For these, uv sync --locked must call the build backend, which fails without the source tree. All other dynamic fields work, including version (hatch-vcs and similar) and requires-python.

Development

uv sync
uv run prek run --all-files

This runs ruff format, ruff check, mypy --strict, the doctests and the tests under coverage (100 % required). The tests in tests/test_integration.py build real projects with uv build and need network access to the package index (marker network). Skip them with uv run pytest -m "not network".

Background: pre-PEP on discuss.python.org.