Root modules

Root modules are always the top-most module. These are special in two ways:

1. Somerules_python bzlmod APIs are only respected by the root module.

2. The root module can force module overrides and specific module dependencyordering.

When configuringrules_python for a root module, you typically want toexplicitly specify the Python version you want to use. This ensures thatdependencies don’t change the Python version out from under you. Remember thatrules_python will set a version by default, but it will change regularly asit tracks a recent Python version.

NOTE: If your root module only uses Python for development of the module itself,you should read the dev-only library module section.

bazel_dep(name="rules_python",version=...)python=use_extension("@rules_python//python/extensions:python.bzl","python")python.defaults(python_version="3.12")python.toolchain(python_version="3.12")

Library modules

A library module is a module that can show up in arbitrary locations in theBzlmod module graph – it’s unknown where in the breadth-first search order themodule will be relative to other modules. For example,rules_python is alibrary module.

# MODULE.bazelbazel_dep(name="rules_python",version=...,dev_dependency=True)python=use_extension("@rules_python//python/extensions:python.bzl","python",dev_dependency=True)python.defaults(python_version="3.12")python.toolchain(python_version="3.12")

# MODULE.bazelbazel_dep(name="rules_python",version=...)

# MODULE.bazelbazel_dep(name="rules_python",version=...)python=use_extension("@rules_python//python/extensions:python.bzl","python")python.toolchain(python_version="3.12")# BUILD.bazelload("@rules_python//python:py_binary.bzl","py_binary")py_binary(...,python_version="3.12")

Pinning to a Python version

Pinning to a version allows targets to force that a specific Python version isused, even if the root module configures a different version as a default. Thisis most useful for two cases:

1. For submodules to ensure they run with the appropriate Python version

2. To allow incremental, per-target, upgrading to newer Python versions,typically in a monorepo situation.

To configure a submodule with the version-aware rules, request the particularversion you need when defining the toolchain:

# MODULE.bazelpython=use_extension("@rules_python//python/extensions:python.bzl","python")python.toolchain(python_version="3.11",)use_repo(python)

Then use the@rules_python repo in yourBUILD file to explicitly pin the Python version when calling the rule:

# BUILD.bazelload("@rules_python//python:py_binary.bzl","py_binary")py_binary(...,python_version="3.11")py_test(...,python_version="3.11")

Multiple versions can be specified and used within a single build.

# MODULE.bazelpython=use_extension("@rules_python//python/extensions:python.bzl","python")python.defaults(# The environment variable takes precedence if set.python_version="3.11",python_version_env="BAZEL_PYTHON_VERSION",)python.toolchain(python_version="3.11",)python.toolchain(python_version="3.12",)# BUILD.bazelload("@rules_python//python:py_binary.bzl","py_binary")load("@rules_python//python:py_test.bzl","py_test")# Defaults to 3.11py_binary(...)py_test(...)# Explicitly use Python 3.11py_binary(...,python_version="3.11")py_test(...,python_version="3.11")# Explicitly use Python 3.12py_binary(...,python_version="3.12")py_test(...,python_version="3.12")

For more documentation, see the bzlmod examples under theexamplesfolder. Look for the examples that contain aMODULE.bazel file.

Other toolchain details

Thepython.toolchain() call makes its contents available under a repo namedpython_X_Y, where X and Y are the major and minor versions. For example,python.toolchain(python_version="3.11") creates the repo@python_3_11.Remember to calluse_repo() to make repos visible to your module:use_repo(python,"python_3_11").

Overriding toolchain defaults and adding more versions

One can perform various overrides for the registered toolchains from the rootmodule. For example, the following use cases would be supported using theexisting attributes:

• Limiting the available toolchains for the entirebzlmod transitive graphviapython.override.available_python_versions.

• Setting particularX.Y.Z Python versions when modules requestX.Y versionviapython.override.minor_mapping.

• Per-version control of the coverage tool used usingpython.single_version_platform_override.coverage_tool.

• Adding additional Python versions viapython.single_version_override orpython.single_version_platform_override.

Registering custom runtimes

Because the python-build-standalone project hasthousands of prebuilt runtimesavailable,rules_python only includes popular runtimes in its built-inconfigurations. If you want to use a runtime that isn’t already known torules_python, thensingle_version_platform_override() can be used to doso. In short, it allows specifying an arbitrary URL and using custom flagsto control when a runtime is used.

In the example below, we register a particular python-build-standalone runtimethat is activated for Linux x86 builds when the custom flag--//:runtime=my-custom-runtime is set.

# File: MODULE.bazelbazel_dep(name="bazel_skylib",version="1.7.1.")bazel_dep(name="rules_python",version="1.5.0")python=use_extension("@rules_python//python/extensions:python.bzl","python")python.single_version_platform_override(platform="my-platform",python_version="3.13.3",sha256="01d08b9bc8a96698b9d64c2fc26da4ecc4fa9e708ce0a34fb88f11ab7e552cbd",os_name="linux",arch="x86_64",target_settings=["@@//:runtime=my-custom-runtime",],urls=["https://github.com/astral-sh/python-build-standalone/releases/download/20250409/cpython-3.13.3+20250409-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"],)# File: //:BUILD.bazelload("@bazel_skylib//rules:common_settings.bzl","string_flag")string_flag(name="custom_runtime",build_setting_default="",)config_setting(name="is_custom_runtime_linux-x86-install-only-stripped",flag_values={":custom_runtime":"linux-x86-install-only-stripped",},)

Notes:

• While any URL and archive can be used, it’s assumed their content looks likea python-build-standalone archive.

• A “version-aware” toolchain is registered, which means the Python version flagmust also match (e.g.,--@rules_python//python/config_settings:python_version=3.13.3must be set – seeminor_mapping andis_default for controls and docsabout version matching and selection).

• Thetarget_compatible_with attribute can be used to entirely specify theargument of the same name that the toolchain uses.

• The labels intarget_settings must be absolute;@@ refers to the main repo.

• Thetarget_settings areconfig_setting targets, which means you cancustomize how matching occurs.

Using defined toolchains from WORKSPACE

It is possible to use toolchains defined inMODULE.bazel inWORKSPACE. For example,the followingMODULE.bazel andWORKSPACE provides a workingpip_parse setup:

# File: WORKSPACEload("@rules_python//python:repositories.bzl","py_repositories")py_repositories()load("@rules_python//python:pip.bzl","pip_parse")pip_parse(name="third_party",requirements_lock="//:requirements.txt",python_interpreter_target="@python_3_10_host//:python",)load("@third_party//:requirements.bzl","install_deps")install_deps()# File: MODULE.bazelbazel_dep(name="rules_python",version="0.40.0")python=use_extension("@rules_python//python/extensions:python.bzl","python")python.defaults(python_version="3.10")python.toolchain(python_version="3.10")use_repo(python,"python_3_10","python_3_10_host")

Note, the user has to import the*_host repository to use the Python interpreter in thepip_parse andwhl_library repository rules, and once that is done,users should be able to ensure the setting of the default toolchain even during thetransition period when some of the code is still defined inWORKSPACE.

Workspace toolchain registration

To register a hermetic Python toolchain rather than rely on a system-installed interpreter for runtime execution, you can add to theWORKSPACE file:

load("@rules_python//python:repositories.bzl","python_register_toolchains")python_register_toolchains(name="python_3_11",# Available versions are listed in @rules_python//python:versions.bzl.# We recommend using the same version your team is already standardized on.python_version="3.11",)load("@rules_python//python:pip.bzl","pip_parse")pip_parse(...python_interpreter_target="@python_3_11_host//:python",...)

After registration, your Python targets will use the toolchain’s interpreter during execution, but a system-installed interpreteris still used to “bootstrap” Python targets (see https://github.com/bazel-contrib/rules_python/issues/691).You may also find some quirks while using this toolchain. Please refer topython-build-standalone documentation’sQuirks section.

Conditionally using local toolchains

By default, a local toolchain has few constraints and is early in the toolchainordering, which means it will usually be used no matter what. This can beproblematic for CI (where it shouldn’t be used), expensive for CI (CI mustinitialize/download the repository to determine its Python version), andannoying for iterative development (enabling/disabling it requires modifyingMODULE.bazel).

These behaviors can be mitigated, but it requires additional configurationto avoid triggering the local toolchain repository to initialize (i.e., runlocal commands and perform downloads).

The two settings to change arelocal_runtime_toolchains_repo.target_compatible_with andlocal_runtime_toolchains_repo.target_settings, which control how Bazeldecides if a toolchain should match. By default, they point to targetswithinthe local runtime repository (triggering repo initialization). We have to overridethem tonot reference the local runtime repository at all.

In the example below, we reconfigure the local toolchains so they are onlyactivated if the custom flag--//:py=local is set and the target platformmatches the Bazel host platform. The net effect is that CI won’t use the localtoolchain (nor initialize its repository), and developers can easilyenable/disable the local toolchain with a command line flag.

# File: MODULE.bazelbazel_dep(name="bazel_skylib",version="1.7.1")local_runtime_toolchains_repo(name="local_toolchains",runtimes=["local_python3"],target_compatible_with={"local_python3":["HOST_CONSTRAINTS"],},target_settings={"local_python3":["@//:is_py_local"]})# File: BUILD.bazelload("@bazel_skylib//rules:common_settings.bzl","string_flag")config_setting(name="is_py_local",flag_values={":py":"local"},)string_flag(name="py",build_setting_default="",)

Autodetecting toolchain

The autodetecting toolchain is a deprecated toolchain that is built into Bazel.Its name is a bit misleading: it doesn’t autodetect anything. All it does isusepython3 from the environment a binary runs within. This provides extremelylimited functionality to the rules (at build time, nothing is knowable aboutthe Python runtime).

Bazel itself automatically registers@bazel_tools//tools/python:autodetecting_toolchainas the lowest priority toolchain. ForWORKSPACE builds, if no other toolchainis registered, that toolchain will be used. For Bzlmod builds,rules_pythonautomatically registers a higher-priority toolchain; it won’t be used unlessthere is a toolchain misconfiguration somewhere.

To aid migration off the Bazel-builtin toolchain,rules_python provides@rules_python//python/runtime_env_toolchains:all. This is an equivalenttoolchain but is implemented usingrules_python’s objects.

Target toolchain type

The target toolchain type is//python:toolchain_type, and itis fortarget configuration runtime information, e.g., the Python versionand interpreter binary that a program will use.

This is typically implemented usingpy_runtime(), whichprovides thePyRuntimeInfo provider. For historical reasons from thePython 2 transition,py_runtime is wrapped inpy_runtime_pair,which providesToolchainInfo with the fieldpy3_runtime, which is aninstance ofPyRuntimeInfo.

This toolchain type is intended to hold onlytarget configuration values. Assuch, when defining its associatedtoolchain target, onlysettoolchain.target_compatible_with and/ortoolchain.target_settings constraints; there is no need tosettoolchain.exec_compatible_with.

Python C toolchain type

The Python C toolchain type (“py cc”) is//python/cc:toolchain_type, andit has C/C++ information for thetarget configuration, e.g., the C headers thatprovidePython.h.

This is typically implemented usingpy_cc_toolchain(), which providesToolchainInfo with the fieldpy_cc_toolchain set, which is aPyCcToolchainInfo provider instance.

This toolchain type is intended to hold onlytarget configuration valuesrelating to the C/C++ information for the Python runtime. As such, when definingits associatedtoolchain target, only settoolchain.target_compatible_with and/ortoolchain.target_settings constraints; there is no need tosettoolchain.exec_compatible_with.

Exec tools toolchain type

The exec tools toolchain type is//python:exec_tools_toolchain_type,and it is for supporting tools forbuilding programs, e.g., the binary toprecompile code at build time.

This toolchain type is intended to hold onlyexec configuration values –usually tools (prebuilt or from-source) used to build Python targets.

This is typically implemented usingpy_exec_tools_toolchain, whichprovidesToolchainInfo with the fieldexec_tools set, which is aninstance ofPyExecToolsInfo.

The toolchain constraints of this toolchain type can be a bit more nuanced thanthe other toolchain types. Typically, you settoolchain.target_settings to the Python version the toolsare for, andtoolchain.exec_compatible_with to the platformthey can run on. This allows the toolchain to first be considered based on thetarget configuration (e.g. Python version), then for one to be chosen based onfinding one compatible with the available host platforms to run the tool on.

However, whattarget_compatible_with/target_settings andexec_compatible_with values to use depends on the details of the tools being used.For example:

• If you had a precompiler that supported any version of Python, thenputting the Python version intarget_settings is unnecessary.

• If you had a prebuilt polyglot precompiler binary that could run on anyplatform, then settingexec_compatible_with is unnecessary.

This can work because, when the rules invoke these build tools, they pass alongall necessary information so that the tool can be entirely independent of thetarget configuration being built for.

Alternatively, if you had a precompiler that only ran on Linux and onlyproduced valid output for programs intended to run on Linux, thenbothexec_compatible_with andtarget_compatible_with must be set to Linux.

Custom toolchain example

Here, we show an example for a semi-complicated toolchain suite, one that is:

• A CPython-based interpreter

• For Python version 3.12.0

• Using an in-build interpreter built from source

• That only runs on Linux

• Using a prebuilt precompiler that only runs on Linux and only producesbytecode valid for 3.12

• With the exec tools interpreter disabled (unnecessary with a prebuiltprecompiler)

• Providing C headers and libraries

Defining toolchains for this might look something like this:

# -------------------------------------------------------# File: toolchain_impl/BUILD# Contains the tool definitions (runtime, headers, libs).# -------------------------------------------------------load("@rules_python//python:py_cc_toolchain.bzl","py_cc_toolchain")load("@rules_python//python:py_exec_tools_toolchain.bzl","py_exec_tools_toolchain")load("@rules_python//python:py_runtime.bzl","py_runtime")load("@rules_python//python:py_runtime_pair.bzl","py_runtime_pair")MAJOR=3MINOR=12MICRO=0py_runtime(name="runtime",interpreter=":python",interpreter_version_info={"major":str(MAJOR),"minor":str(MINOR),"micro":str(MICRO),}implementation="cpython")py_runtime_pair(name="runtime_pair",py3_runtime=":runtime")py_cc_toolchain(name="py_cc_toolchain_impl",headers=":headers",libs=":libs",python_version="{}.{}".format(MAJOR,MINOR))py_exec_tools_toolchain(name="exec_tools_toolchain_impl",exec_interpreter="@rules_python/python:none",precompiler="precompiler-cpython-3.12")cc_binary(name="python3.12",...)cc_library(name="headers",...)cc_library(name="libs",...)# ------------------------------------------------------------------# File: toolchains/BUILD# Putting toolchain() calls in a separate package from the toolchain# implementations minimizes Bazel loading overhead.# ------------------------------------------------------------------toolchain(name="runtime_toolchain",toolchain="//toolchain_impl:runtime_pair",toolchain_type="@rules_python//python:toolchain_type",target_compatible_with=["@platforms/os:linux"],)toolchain(name="py_cc_toolchain",toolchain="//toolchain_impl:py_cc_toolchain_impl",toolchain_type="@rules_python//python/cc:toolchain_type",target_compatible_with=["@platforms/os:linux"],)toolchain(name="exec_tools_toolchain",toolchain="//toolchain_impl:exec_tools_toolchain_impl",toolchain_type="@rules_python//python:exec_tools_toolchain_type",target_settings=["@rules_python//python/config_settings:is_python_3.12",],exec_compatible_with=["@platforms/os:linux"],)# -----------------------------------------------# File: MODULE.bazel or WORKSPACE.bazel# These toolchains will be considered before others.# -----------------------------------------------register_toolchains("//toolchains:all")

When registering custom toolchains, be aware of thetoolchain registrationorder. In brief,toolchain order is the BFS-order of the modules; see the Bazel docs for a moredetailed description.

Differences from//python/bin:repl

The//python/bin:python target provides access to the underlying interpreterwithout any hermeticity guarantees.

The//python/bin:repl target provides an environment identical towhatpy_binary provides. That means it handles things like thePYTHONSAFEPATHenvironment variable automatically. The//python/bin:python target will not.