blob: 78c88c5f46b3ed5043e36c8c83f3008e5857c97b [file] [view]
:::{default-domain} bzl
:::
# Lock
:::{note}
`rules_python` supports `requirements.txt` and `uv.lock` (bzlmod only)
formats.
#{gh-issue}`2787` tracks `pylock.toml` support.
:::
## requirements.txt
### pip compile
Generally, when working on a Python project, you'll have some dependencies that themselves have
other dependencies. You might also specify dependency bounds instead of specific versions.
So you'll need to generate a full list of all transitive dependencies and pinned versions
for every dependency.
Typically, you'd have your project dependencies specified in `pyproject.toml` or `requirements.in`
and generate the full pinned list of dependencies in `requirements_lock.txt`, which you can
manage with {obj}`compile_pip_requirements`:
```starlark
load("@rules_python//python:pip.bzl", "compile_pip_requirements")
compile_pip_requirements(
name = "requirements",
src = "pyproject.toml",
requirements_txt = "requirements_lock.txt",
)
```
This rule generates two targets:
- `bazel run [name].update` will regenerate the `requirements_txt` file
- `bazel test [name]_test` will test that the `requirements_txt` file is up to date
Once you generate this fully specified list of requirements, you can install the requirements ([bzlmod](./download)/[WORKSPACE](./download-workspace)).
:::{warning}
If you're specifying dependencies in `pyproject.toml`, make sure to include the
`[build-system]` configuration, with pinned dependencies.
`compile_pip_requirements` will use the build system specified to read your
project's metadata, and you might see non-hermetic behavior if you don't pin the
build system.
Not specifying `[build-system]` at all will result in using a default
`[build-system]` configuration, which uses unpinned versions
([ref](https://peps.python.org/pep-0518/#build-system-table)).
:::
#### pip compile Dependency groups
pip-compile doesn't yet support pyproject.toml dependency groups. Follow
[pip-tools #2062](https://github.com/jazzband/pip-tools/issues/2062)
to see the status of their support.
In the meantime, support can be emulated by passing multiple files to `srcs`:
```starlark
compile_pip_requirements(
srcs = ["pyproject.toml", "requirements-dev.in"]
...
)
```
### uv pip compile (bzlmod only)
We also have a setup for the `uv pip compile` way of generating lock files.
This is well tested with the public PyPI index, but you may hit some rough
edges with private mirrors.
#### Example usage
```starlark
load("@rules_python//python/uv:lock.bzl", "lock")
lock(
name = "requirements",
srcs = ["pyproject.toml", "requirements.in"],
out = "requirements_lock.txt",
)
```
#### `[tool.uv]` settings from pyproject.toml
When a `pyproject.toml` file is among the {arg}`lock.srcs`, the
{obj}`lock` rule auto-detects the project directory and passes
`--project <dir>` to `uv`. This causes `uv` to read
`[tool.uv]` settings from that `pyproject.toml`, such as
`no-build-isolation`, `exclude-dependencies`, and workspace members.
If multiple `pyproject.toml` files are in {arg}`lock.srcs`, the one
with the shortest directory path is selected (this heuristic works for
typical uv workspace layouts where the root configuration is at the
shortest path).
If the auto-detection picks the wrong project directory, use the
`project` parameter to override:
```starlark
lock(
name = "requirements",
srcs = ["pyproject.toml", "requirements.in"],
out = "requirements_lock.txt",
project = "subproject",
)
```
:::{warning}
**Known limitations of auto-detection**
1. **Workspace heuristic** — the shortest-path selection may incorrectly assume
the upper-most workspace `pyproject.toml` is the correct one. For monorepos
with multiple independent sub-projects, you must set `project` explicitly
for each {obj}`lock` target.
1. **No test target** — unlike {obj}`compile_pip_requirements`, no test target
is auto-created; see the {obj}`lock` docs for how to add one manually using
`diff_test` from `bazel_skylib`.
:::
## uv.lock (bzlmod only)
The {obj}`lock` rule also supports generating cross-platform `uv.lock` files
using `uv lock` when {arg}`lock.out` ends with `.lock` (such as `uv.lock`).
### Example usage
In `BUILD.bazel`:
```starlark
load("@rules_python//python/uv:lock.bzl", "lock")
lock(
name = "uv_lock",
srcs = ["pyproject.toml"],
out = "uv.lock",
)
```
Run `bazel run //:uv_lock.update` to generate or update `uv.lock`, then pass it
to {obj}`pip.parse` in `MODULE.bazel` via {attr}`pip.parse.uv_lock`:
```starlark
pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
pip.parse(
hub_name = "my_deps",
python_version = "3.13",
uv_lock = "//:uv.lock",
)
use_repo(pip, "my_deps")
```
`[tool.uv]` settings auto-detection and the {arg}`lock.project` attribute work
the same way as described in the `uv pip compile` section above.
For more documentation see {obj}`lock`.