Skip to main content
Version: 0.17.x

pip

Import pip requirements into Bazel.

Rules

whl_library_alias​

Example usage (generated):

load("@rules_python//python:pip.bzl", "whl_library_alias")

whl_library_alias(
    # A unique name for this repository.
    name = "",
    default_version = "",
    # A dictionary from local repository name to global repository name
    repo_mapping = {},
    version_map = {},
    wheel_name = "",
)

name​

Required name.

A unique name for this repository.

default_version​

Required string.

repo_mapping​

Required dictionary: String → String.

A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

version_map​

Required dictionary: String → String.

wheel_name​

Required string.

Macros and Functions

compile_pip_requirements​

Generates targets for managing pip dependencies with pip-compile.

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 (e.g. with -r ../other/requirements.txt).

It also generates two targets for running pip-compile:

  • validate with bazel test <name>_test
  • update with bazel run <name>.update

Example usage (generated):

load("@rules_python//python:pip.bzl", "compile_pip_requirements")

compile_pip_requirements(
    # base name for generated targets, typically "requirements".
    name = "",
)

name​

Required.

base name for generated targets, typically "requirements".

extra_args​

Optional. Default: []

passed to pip-compile.

extra_deps​

Optional. Default: []

extra dependencies passed to pip-compile.

py_binary​

Optional. Default: <function py_binary>

the py_binary rule to be used.

py_test​

Optional. Default: <function py_test>

the py_test rule to be used.

requirements_in​

Optional. Default: None

file expressing desired dependencies.

requirements_txt​

Optional. Default: None

result of "compiling" the requirements.in file.

requirements_darwin​

Optional. Default: None

File of darwin specific resolve output to check validate if requirement.in has changes.

requirements_linux​

Optional. Default: None

File of linux specific resolve output to check validate if requirement.in has changes.

requirements_windows​

Optional. Default: None

File of windows specific resolve output to check validate if requirement.in has changes.

visibility​

Optional. Default: ["//visibility:private"]

passed to both the _test and .update rules.

tags​

Optional. Default: None

tagging attribute common to all build rules, passed to both the _test and .update rules.

kwargs​

Optional.

other bazel attributes passed to the "_test" rule.

multi_pip_parse​

NOT INTENDED FOR DIRECT USE!

This is intended to be used by the multi_pip_parse implementation in the template of the multi_toolchain_aliases repository rule.

Example usage (generated):

load("@rules_python//python:pip.bzl", "multi_pip_parse")

multi_pip_parse(
    # the name of the multi_pip_parse repository.
    name = "",
    # the default Python version.
    default_version = None,
    # all Python toolchain versions currently registered.
    python_versions = None,
    # a dictionary which keys are Python versions and values are resolved host interpreters.
    python_interpreter_target = None,
    # a dictionary which keys are Python versions and values are locked requirements files.
    requirements_lock = None,
)

name​

Required.

the name of the multi_pip_parse repository.

default_version​

Required.

the default Python version.

python_versions​

Required.

all Python toolchain versions currently registered.

python_interpreter_target​

Required.

a dictionary which keys are Python versions and values are resolved host interpreters.

requirements_lock​

Required.

a dictionary which keys are Python versions and values are locked requirements files.

kwargs​

Optional.

extra arguments passed to all wrapped pip_parse.

package_annotation​

Annotations to apply to the BUILD file content from package generated from a pip_repository rule.

Example usage (generated):

load("@rules_python//python:pip.bzl", "package_annotation")

package_annotation(
)

additive_build_content​

Optional. Default: None

Raw text to add to the generated BUILD file of a package.

copy_files​

Optional. Default: {}

A mapping of src and out files for @bazel_skylib//rules:copy_file.bzl

copy_executables​

Optional. Default: {}

A mapping of src and out files for @bazel_skylib//rules:copy_file.bzl. Targets generated here will also be flagged as executable.

data​

Optional. Default: []

A list of labels to add as data dependencies to the generated py_library target.

data_exclude_glob​

Optional. Default: []

A list of exclude glob patterns to add as data to the generated py_library target.

srcs_exclude_glob​

Optional. Default: []

A list of labels to add as srcs to the generated py_library target.

pip_install​

Accepts a locked/compiled requirements file and installs the dependencies listed within.

load("@rules_python//python:pip.bzl", "pip_install")

pip_install(
    name = "pip_deps",
    requirements = ":requirements.txt",
)

load("@pip_deps//:requirements.bzl", "install_deps")

install_deps()

requirements​

Optional. Default: None

A 'requirements.txt' pip requirements file.

name​

Optional. Default: "pip"

A unique name for the created external repository (default 'pip').

kwargs​

Optional.

Additional arguments to the pip_repository repository rule.

pip_parse​

Accepts a locked/compiled requirements file and installs the dependencies listed within.

Those dependencies become available in a generated requirements.bzl file. You can instead check this requirements.bzl file into your repo, see the "vendoring" section below.

This macro wraps the pip_repository rule that invokes pip. In your WORKSPACE file:

load("@rules_python//python:pip.bzl", "pip_parse")

pip_parse(
    name = "pip_deps",
    requirements_lock = ":requirements.txt",
)

load("@pip_deps//:requirements.bzl", "install_deps")

install_deps()

You can then reference installed dependencies from a BUILD file with:

load("@pip_deps//:requirements.bzl", "requirement")

py_library(
    name = "bar",
    ...
    deps = [
       "//my/other:dep",
       requirement("requests"),
       requirement("numpy"),
    ],
)

In addition to the requirement macro, which is used to access the generated py_library target generated from a package's wheel, The generated requirements.bzl file contains functionality for exposing entry points as py_binary targets as well.

load("@pip_deps//:requirements.bzl", "entry_point")

alias(
    name = "pip-compile",
    actual = entry_point(
        pkg = "pip-tools",
        script = "pip-compile",
    ),
)

Note that for packages whose name and script are the same, only the name of the package is needed when calling the entry_point macro.

load("@pip_deps//:requirements.bzl", "entry_point")

alias(
    name = "flake8",
    actual = entry_point("flake8"),
)

Vendoring the requirements.bzl file​

In some cases you may not want to generate the requirements.bzl file as a repository rule while Bazel is fetching dependencies. For example, if you produce a reusable Bazel module such as a ruleset, you may want to include the requirements.bzl file rather than make your users install the WORKSPACE setup to generate it. See https://github.com/bazelbuild/rules_python/issues/608

This is the same workflow as Gazelle, which creates go_repository rules with update-repos

To do this, use the "write to source file" pattern documented in https://blog.aspect.build/bazel-can-write-to-the-source-folder to put a copy of the generated requirements.bzl into your project. Then load the requirements.bzl file directly rather than from the generated repository. See the example in rules_python/examples/pip_parse_vendored.

requirements​

Optional. Default: None

Deprecated. See requirements_lock.

requirements_lock​

Optional. Default: None

A fully resolved 'requirements.txt' pip requirement file containing the transitive set of your dependencies. If this file is passed instead of 'requirements' no resolve will take place and piprepository will create individual repositories for each of your dependencies so that wheels are fetched/built only for the targets specified by 'build/run/test'. Note that if your lockfile is platform-dependent, you can use the `requirements[platform]` attributes.

name​

Optional. Default: "pip_parsed_deps"

The name of the generated repository. The generated repositories containing each requirement will be of the form <name>_<requirement-name>.

bzlmod​

Optional. Default: False

Whether this rule is being run under a bzlmod module extension.

kwargs​

Optional.

Additional arguments to the pip_repository repository rule.

Last updated on by Alex Eagle