config_settings

flag --//python/config_settings:add_srcs_to_runfiles

Determines if the srcs of targets are added to their runfiles.

More specifically, the sources added to runfiles are the .py files in srcs. If precompiling is performed, it is the .py files that are kept according to precompile_source_retention.

Values:

auto: (default) Automatically decide the effective value; the current behavior is disabled.
disabled: Don’t add srcs to a target’s runfiles.
enabled: Add srcs to a target’s runfiles.

Added in version 0.37.0.

Deprecated since version 0.37.0: This is a transition flag and will be removed in a subsequent release.

flag --//python/config_settings:build_python_zip

Controls if a py_binary/py_test output is a self-executable zipapp.

When enabled, the output of py_binary or py_test targets will be a self-executable zipapp.

Note

This affects all py_binary and py_test targets in the build, not only the target(s) specified on the command line.

Values:

true
false

This flag replaces the Bazel builtin --build_python_zip flag.

Added in version 1.7.0.

flag --//python/config_settings:debugger

A target for providing a custom debugger dependency.

This flag is roughly equivalent to putting a target in deps. It allows injecting a dependency into executables (py_binary, py_test) without having to modify their deps. The expectation is it points to a target that provides an alternative debugger (pudb, winpdb, debugpy, etc).

Must provide PyInfo.
This dependency is only used for the target config, i.e. build tools don’t have it added.

Note

Setting this flag adds the debugger dependency, but doesn’t automatically set PYTHONBREAKPOINT to change breakpoint() behavior.

Added in version VERSION_NEXT_FEATURE.

flag --//python/config_settings:experimental_python_import_all_repositories

Controls whether repository directories are added to the import path.

When enabled, the top-level directories in the runfiles root directory (which are presumbed to be repository directories) are added to the Python import search path.

It’s recommended to set this to false to avoid external dependencies unexpectedly interferring with import searching.

Values;

true (default)
false

This flag replaces the Bazel builtin --experimental_python_import_all_repositories flag.

Added in version 1.7.0.

flag --//python/config_settings:python_path

A fallback path to use for Python for particular legacy Windows-specific code paths.

Deprecated, do not use. This flag is largely a no-op and was replaced by toolchains. It only remains for some legacy Windows code-paths that will be removed.

This flag replaces the Bazel builtin --python_path flag.

Deprecated since version 1.7.0: Use toolchains instead.

Added in version 1.7.0.

flag --//python/config_settings:python_version: Determines the default hermetic Python toolchain version. This can be set to one of the values that rules_python maintains.

//python/config_settings:python_version_major_minor: Parses the value of the python_version and transforms it into a X.Y value.

flag --//python/config_settings:incompatible_default_to_explicit_init_py

Controls if missing __init__.py files are generated or not.

If false, py_binary and py_test will, for every *.py and *.so file, create __init__.py files for the containing directory, and all parent directories, that do not already have an __init__.py file. If true, this behavior is disabled.

It’s recommended to disable this behavior to avoid surprising import effects from directories being importable when they otherwise wouldn’t be, and for how it can interfere with implicit namespace packages.

Values:

true: do not generate missing __init__.py files
false (default): generate missing __init__.py files

This flag replaces the Bazel builtin --incompatible_default_to_explicit_init_py flag.

Added in version 1.7.0.

//python/config_settings:is_python_*

config_settings to match Python versions

The name pattern is is_python_X.Y (to match major.minor) and is_python_X.Y.Z (to match major.minor.patch).

Note that the set of available targets depends on the configured TOOL_VERSIONS. Versions may not always be available if the root module has customized them, or as older Python versions are removed from rules_python’s set of builtin, known versions.

If you need to match a version that isn’t present, then you have two options:

Manually define a config_setting and have it match --python_version or python_version_major_minor. This works best when you don’t control the root module, or don’t want to rely on the MODULE.bazel configuration. Such a config settings would look like:

# Match any 3.5 version
config_setting(
    name = "is_python_3.5",
    flag_values = {
        "@rules_python//python/config_settings:python_version_major_minor": "3.5",
    }
)
# Match exactly 3.5.1
config_setting(
    name = "is_python_3.5.1",
    flag_values = {
        "@rules_python//python/config_settings:python_version": "3.5.1",
    }
)

Use python.single_override to re-introduce the desired version so that the corresponding //python/config_setting:is_python_XXX target is generated.

flag --//python/config_settings:exec_tools_toolchain

Determines if the exec_tools_toolchain_type toolchain is enabled.

Note

Note that this only affects the rules_python generated toolchains.

Values:

enabled: Allow matching of the registered toolchains at build time.
disabled: Prevent the toolchain from being matched at build time.

Added in version 0.33.2.

flag --//python/config_settings:precompile

Determines if Python source files should be compiled at build time.

Note

The flag value is overridden by the target level precompile attribute, except for the case of force_enabled and forced_disabled.

Values:

auto: (default) Automatically decide the effective value based on environment, target platform, etc.
enabled: Compile Python source files at build time.
disabled: Don’t compile Python source files at build time.
force_enabled: Like enabled, except overrides target-level setting. This is mostly useful for development, testing enabling precompilation more broadly, or as an escape hatch if build-time compiling is not available.
force_disabled: Like disabled, except overrides target-level setting. This is useful useful for development, testing enabling precompilation more broadly, or as an escape hatch if build-time compiling is not available.

Added in version 0.33.0.

Changed in version 0.37.0: The if_generated_source value was removed

flag --//python/config_settings:precompile_source_retention

Determines, when a source file is compiled, if the source file is kept in the resulting output or not.

Note

This flag is overridden by the target level precompile_source_retention attribute.

Values:

auto: (default) Automatically decide the effective value based on environment, target platform, etc.
keep_source: Include the original Python source.
omit_source: Don’t include the orignal py source.

Added in version 0.33.0.

Added in version 0.36.0: The auto value

Changed in version 0.37.0: The omit_if_generated_source value was removed

flag --//python/config_settings:py_linux_libc

Set what libc is used for the target platform. This will affect which whl binaries will be pulled and what toolchain will be auto-detected. Currently rules_python only supplies toolchains compatible with glibc.

Values:

glibc: Use glibc, default.
muslc: Use muslc.

Added in version 0.33.0.

flag --//python/config_settings:py_freethreaded

Set whether to use an interpreter with the experimental freethreaded option set to true.

Values:

no: Use regular Python toolchains, default.
yes: Use the experimental Python toolchain with freethreaded compile option enabled.

Added in version 0.38.0.

flag --//python/config_settings:pip_env_marker_config

The target that provides the values for pip env marker evaluation.

Default: //python/config_settings:_pip_env_marker_default_config

This flag points to a target providing EnvMarkerInfo, which determines the values used when environment markers are resolved at build time.

Added in version 1.5.0.

flag --//python/config_settings:pip_whl

Set what distributions are used in the pip integration.

Values:

auto: Prefer whl distributions if they are compatible with a target platform, but fallback to sdist. This is the default.
only: Only use whl distributions and error out if it is not available.
no: Only use sdist distributions. The wheels will be built non-hermetically in the whl_library repository rule.

Added in version 0.33.0.

flag --//python/config_settings:pip_whl_osx_arch

Set what wheel types we should prefer when building on the OSX platform.

Values:

arch: Prefer architecture specific wheels.
universal: Prefer universal wheels that usually are bigger and contain binaries for both, Intel and ARM architectures in the same wheel.

Added in version 0.33.0.

flag --//python/config_settings:pip_whl_glibc_version

Set the minimum glibc version that the py_binary using whl distributions from a PyPI index should support.

Values:

"": Select the lowest available version of each wheel giving you the maximum compatibility. This is the default.
X.Y: The string representation of a glibc version. The allowed values depend on the requirements.txt lock file contents.

Added in version 0.33.0.

flag --//python/config_settings:pip_whl_muslc_version

Set the minimum muslc version that the py_binary using whl distributions from a PyPI index should support.

Values:

"": Select the lowest available version of each wheel giving you the maximum compatibility. This is the default.
X.Y: The string representation of a muslc version. The allowed values depend on the requirements.txt lock file contents.

Added in version 0.33.0.

flag --//python/config_settings:pip_whl_osx_version

Set the minimum osx version that the py_binary using whl distributions from a PyPI index should support.

Values:

"": Select the lowest available version of each wheel giving you the maximum compatibility. This is the default.
X.Y: The string representation of the MacOS version. The allowed values depend on the requirements.txt lock file contents.

Added in version 0.33.0.

flag --//python/config_settings:venvs_site_packages

Determines if libraries use a site-packages layout for their files.

Note this flag only affects PyPI dependencies of --bootstrap_impl=script binaries

Warning

Experimental API. This API is still under development and may change or be removed without notice.

Values:

no (default): Make libraries importable by adding to sys.path
yes: Make libraries importable by creating paths in a binary’s site-packages directory.

flag --//python/config_settings:bootstrap_impl

Determine how programs implement their startup process.

Values:

system_python: (default) Use a bootstrap that requires a system Python available in order to start programs. This requires PyRuntimeInfo.bootstrap_template to be a Python program.
script: Use a bootstrap that uses an arbitrary executable script (usually a shell script) instead of requiring it be a Python program.

Note

The script bootstrap requires the toolchain to provide the PyRuntimeInfo provider from rules_python. This loosely translates to using Bazel 7+ with a toolchain created by rules_python. Most notably, WORKSPACE builds default to using a legacy toolchain built into Bazel itself which doesn’t support the script bootstrap. If not available, the system_python bootstrap will be used instead.