docs/environment-variables.md

# Environment Variables

::::{envvar} RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS

This variable allows for additional arguments to be provided to the Python interpreter
at bootstrap time when the `bash` bootstrap is used. If
`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` were provided as `-Xaaa`, then the command
would be:

```
python -Xaaa /path/to/file.py
```

This feature is useful for the integration of debuggers. For example,
it would be possible to configure `RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` to
be set to `/path/to/debugger.py --port 12344 --file`, resulting
in the command executed being:

```
python /path/to/debugger.py --port 12345 --file /path/to/file.py
```

:::{seealso}
The {bzl:obj}`interpreter_args` attribute.

The guide on {any}`How to integrate a debugger`
:::

:::{versionadded} 1.3.0
:::
:::{versionchanged} 1.7.0
Support added for {bzl:flag}`--bootstrap_impl=system_python`.
:::

::::

:::{envvar} RULES_PYTHON_BOOTSTRAP_VERBOSE

When `1`, debug information about bootstrapping of a program is printed to
stderr.
:::

:::{envvar} RULES_PYTHON_BZLMOD_DEBUG

When `1`, bzlmod extensions will print debug information about what they're
doing. This is mostly useful for development to debug errors.
:::

:::{envvar} RULES_PYTHON_DEPRECATION_WARNINGS

When `1`, `rules_python` will warn users about deprecated functionality that will
be removed in a subsequent major `rules_python` version. Defaults to `0` if unset.
:::

::::{envvar} RULES_PYTHON_EXTRACT_ROOT

Directory to use as the root for creating files necessary for bootstrapping so
that a binary can run.

Only applicable when {bzl:flag}`--venvs_use_declare_symlink=no` is used.

When set, a binary will attempt to find a unique, reusable, location within this
directory for the files it needs to create to aid startup. The files may not be
deleted upon program exit; it is the responsibility of the caller to ensure
cleanup.

Manually specifying the directory is useful to lower the overhead of
extracting/creating files on every program execution. By using a location
outside /tmp, longer lived programs don't have to worry about files in /tmp
being cleaned up by the OS.

If not set, then a temporary directory will be created and deleted upon program
exit.

:::{versionadded} 1.2.0
:::
::::

:::{envvar} RULES_PYTHON_GAZELLE_VERBOSE

When `1`, debug information from Gazelle is printed to stderr.
::::

:::{envvar} RULES_PYTHON_PIP_ISOLATED

Determines if `--isolated` is used with pip.

Valid values:
* `0` and `false` mean to not use isolated mode
* Other non-empty values mean to use isolated mode.
:::

::::{envvar} RULES_PYTHON_PYCACHE_DIR

Determines the directory that runtime-generated pyc cache files will
be stored in.

This directory may be reused between invocations, depending on the sandboxing
configuration. Setting it to `/dev/null` will, in effect, disable runtime
pyc caching. By setting e.g.
`--sandbox_add_mount_pair=$HOME/.cache/rules_python_pycache`, it's possible for
pyc caching to persist across invocations.

**Behavior specific to downloaded runtimes:**
First `RULES_PYTHON_PYCACHE_DIR` is checked. If set, it is used as-is for
the root pycache directory.

Otherwise, the following environment variables are checked in the following
order. Their values will have `rules_python_pycache` appended to them to form
the root pycache directory:
1. `XDG_CACHE_HOME`.
2. `$HOME/.cache` (non-Windows), the XDG default when `XDG_CACHE_HOME` is
   unset, or `LOCALAPPDATA` (Windows).

If `/dev/null` (`NUL` on Windows) is specified, or if a directory cannot be
found or created, then pyc caching will be disabled.

:::{versionchanged} VERSION_NEXT_PATCH
Temporary directories (`TMP`, `TEMP`, `/tmp` and `C:\Temp`) are no longer used.
They get cleaned out while the fetched runtime persists, which left the
`__pycache__` symlinks dangling.
:::

::::

:::{envvar} RULES_PYTHON_PYPI_HUB_RESERVED

When `1`, any PyPI hub named `"pypi"` will be renamed to `<module_name>_pypi`
to prevent name collisions with the unified `@pypi` proxy repository, and
a warning is printed indicating that the renaming occurred. If not set (defaulting
to `0`), a warning is printed advising to rename the hub, and the collision
is not resolved.

:::{versionadded} 2.2.0
:::

:::

:::{envvar} RULES_PYTHON_REPO_DEBUG

When `1`, repository rules will print debug information about what they're
doing. This is mostly useful for development to debug errors.
:::

:::{envvar} RULES_PYTHON_REPO_DEBUG_VERBOSITY

Determines the verbosity of logging output for repo rules. Valid values:

* `DEBUG`
* `FAIL`
* `INFO`
* `TRACE`
:::

:::{envvar} RULES_PYTHON_REPO_TOOLCHAIN_VERSION_OS_ARCH

Determines the Python interpreter platform to be used for a particular
interpreter `(version, os, arch)` triple to be used in repository rules.
Replace the `VERSION_OS_ARCH` part with actual values when using, e.g.,
`3_13_0_linux_x86_64`. The version values must have `_` instead of `.` and the
os, arch values are the same as the ones mentioned in the
`//python:versions.bzl` file.
:::

:::{envvar} VERBOSE_COVERAGE

When `1`, debug information about coverage behavior is printed to stderr.
:::

## Removed Environment Variables

:::{versionremoved} 2.1.0
The following environment variables were removed:

* `RULES_PYTHON_ENABLE_PYSTAR`: Used to enable the Starlark implementation of
  core rules.
* `RULES_PYTHON_ENABLE_PIPSTAR`: Used to enable the Starlark implementation of
  PyPI integration.
:::