1# Bzlmod support 2 3## `rules_python` `bzlmod` support 4 5- Status: GA 6- Full Feature Parity: No 7 - `rules_python`: Yes 8 - `rules_python_gazelle_plugin`: No (see below). 9 10In general `bzlmod` has more features than `WORKSPACE` and users are encouraged to migrate. 11 12## Configuration 13 14The releases page will give you the latest version number, and a basic example. The release page is located [here](/bazelbuild/rules_python/releases). 15 16## What is bzlmod? 17 18> Bazel supports external dependencies, source files (both text and binary) used in your build that are not from your workspace. For example, they could be a ruleset hosted in a GitHub repo, a Maven artifact, or a directory on your local machine outside your current workspace. 19> 20> As of Bazel 6.0, there are two ways to manage external dependencies with Bazel: the traditional, repository-focused WORKSPACE system, and the newer module-focused MODULE.bazel system (codenamed Bzlmod, and enabled with the flag `--enable_bzlmod`). The two systems can be used together, but Bzlmod is replacing the WORKSPACE system in future Bazel releases. 21> -- <cite>https://bazel.build/external/overview</cite> 22 23## Examples 24 25We have two examples that demonstrate how to configure `bzlmod`. 26 27The first example is in [examples/bzlmod](examples/bzlmod), and it demonstrates basic bzlmod configuration. 28A user does not use `local_path_override` stanza and would define the version in the `bazel_dep` line. 29 30A second example, in [examples/bzlmod_build_file_generation](examples/bzlmod_build_file_generation) demonstrates the use of `bzlmod` to configure `gazelle` support for `rules_python`. 31 32## Differences in behavior from WORKSPACE 33 34### Default toolchain is not the local system Python 35 36Under bzlmod, the default toolchain is no longer based on the locally installed 37system Python. Instead, a recent Python version using the pre-built, 38standalone runtimes are used. 39 40If you need the local system Python to be your toolchain, then it's suggested 41that you setup and configure your own toolchain and register it. Note that using 42the local system's Python is not advised because will vary between users and 43platforms. 44 45If you want to use the same toolchain as what WORKSPACE used, then manually 46register the builtin Bazel Python toolchain by doing 47`register_toolchains("@bazel_tools//tools/python:autodetecting_toolchain")`. 48 49Note that using this builtin Bazel toolchain is deprecated and unsupported. 50See the {obj}`runtime_env_toolchains` docs for a replacement that is marginally 51better supported. 52**IMPORTANT: this should only be done in a root module, and may interfere with 53the toolchains rules_python registers**. 54 55NOTE: Regardless of your toolchain, due to 56[#691](https://github.com/bazelbuild/rules_python/issues/691), `rules_python` 57still relies on a local Python being available to bootstrap the program before 58handing over execution to the toolchain Python. 59 60To override this behaviour see {obj}`--bootstrap_impl=script`, which switches 61to `bash`-based bootstrap on UNIX systems. 62 63### Better PyPI package downloading on bzlmod 64 65On `bzlmod` users have the option to use the `bazel_downloader` to download packages 66and work correctly when `host` platform is not the same as the `target` platform. This 67provides faster package download times and integration with the credentials helper. 68 69### Extra targets in `whl_library` repos 70 71Due to how `bzlmod` is designed and the visibility rules that it enforces, it is best to use 72the targets in the `whl` repos as they do not rely on using the `annotations` API to 73add extra targets to so-called `spoke` repos. For alternatives that should cover most of the 74existing usecases please see: 75* {bzl:obj}`py_console_script_binary` to create `entry_point` targets. 76* {bzl:obj}`whl_filegroup` to extract filegroups from the `whl` targets (e.g. `@pip//numpy:whl`) 77* {bzl:obj}`pip.override` to patch the downloaded `whl` files. Using that you 78 can change the `METADATA` of the `whl` file that will influence how 79 `rules_python` code generation behaves. 80