Usage

# pyproject.toml
[build-system]
requires = [
    "hatchling",
    "hatch-pinned-extra>=0.4.0,<1",
]
build-backend = "hatchling.build"

[tool.hatch.metadata.hooks.pinned_extra]
name = "pinned"

If your package doesn't have any optional dependencies already, you will need to mark them as dynamic:

# pyproject.toml
[project]
dynamic = [
    "optional-dependencies",
]

Reading pinned dependencies from pylock.toml file

To use a pylock.toml file instead of uv.lock, set lockfile to the file path:

[tool.hatch.metadata.hooks.pinned_extra]
lockfile = "pylock.prod.toml"

Enabling the Plugin

The plugin requires the HATCH_PINNED_EXTRA_ENABLE environment variable to be set to a truthy value to activate (e.g. 1, true, yes, on). This design allows you to control when pinned dependencies are included:

# Build with pinned dependencies
HATCH_PINNED_EXTRA_ENABLE=1 uv build

# Update lockfile without constraints from pinned dependencies
uv lock --upgrade

This approach solves the circular dependency issue where pinned dependencies become constraints during uv lock --upgrade, preventing actual upgrades.