bazel-contrib · aignas · Jul 15, 2025 · Jul 14, 2025 · Jul 15, 2025
@@ -5,6 +5,8 @@
 
 :::{note}
 Currently `rules_python` only supports `requirements.txt` format.
+
+#{gh-issue}`2787` tracks `pylock.toml` support.
 :::
 
 ## requirements.txt
@@ -37,11 +39,33 @@ This rule generates two targets:
 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.
+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)).
+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 experimental setup for the `uv pip compile` way of generating lock files.

@@ -40,7 +40,7 @@ def pip_compile(
         tags = None,
         constraints = [],
         **kwargs):
-    """Generates targets for managing pip dependencies with pip-compile.
+    """Generates targets for managing pip dependencies with pip-compile (piptools).
 
     By default this rules generates a filegroup named "[name]" which can be included in the data
     of some other compile_pip_requirements rule that references these requirements
@@ -65,7 +65,10 @@ def pip_compile(
             * a requirements text file, usually named `requirements.in`
             * A `.toml` file, where the `project.dependencies` list is used as per
               [PEP621](https://peps.python.org/pep-0621/).
-        extra_args: passed to pip-compile.
+        extra_args: passed to pip-compile (aka `piptools`). See the
+            [pip-compile docs](https://pip-tools.readthedocs.io/en/latest/cli/pip-compile)
+            for args and meaning (passing `-h` and/or `--version` can help
+            inform what args are available)
         extra_deps: extra dependencies passed to pip-compile.
         generate_hashes: whether to put hashes in the requirements_txt file.
         py_binary: the py_binary rule to be used.