From a247254edfef6a06c225821f63bcc70d1fd4251c Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Mon, 11 Nov 2024 09:40:57 -0600 Subject: [PATCH] Update format of environment variable reference --- .../uv-dev/src/generate_env_vars_reference.rs | 49 +- docs/configuration/environment.md | 702 +++++++++++++----- 2 files changed, 542 insertions(+), 209 deletions(-) diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/crates/uv-dev/src/generate_env_vars_reference.rs index 9e6467b01be5b..b4d2cc69e9058 100644 --- a/crates/uv-dev/src/generate_env_vars_reference.rs +++ b/crates/uv-dev/src/generate_env_vars_reference.rs @@ -2,6 +2,7 @@ use anyhow::bail; use pretty_assertions::StrComparison; +use std::collections::BTreeSet; use std::path::PathBuf; use uv_static::EnvVars; @@ -71,30 +72,38 @@ fn generate() -> String { let mut output = String::new(); output.push_str("# Environment variables\n\n"); - output.push_str("uv respects the following environment variables:\n\n"); - - for (var, doc) in EnvVars::metadata() { - // Remove empty lines and ddd two spaces to the beginning from the second line. - let doc = doc - .lines() - .enumerate() - .filter(|(_, line)| !line.trim().is_empty()) - .map(|(i, line)| { - if i == 0 { - line.to_string() - } else { - format!(" {line}") - } - }) - .collect::>() - .join("\n"); - output.push_str(&format!( - "- [`{var}`](#{var}): {doc}\n" - )); + + // Partition and sort environment variables into UV_ and external variables. + let (uv_vars, external_vars): (BTreeSet<_>, BTreeSet<_>) = EnvVars::metadata() + .iter() + .partition(|(var, _)| var.starts_with("UV_")); + + output.push_str("uv defines and respects the following environment variables:\n\n"); + + for (var, doc) in uv_vars { + output.push_str(&render(&var, &doc)); + } + + output.push_str("\n\n## Externally defined variables\n\n"); + output.push_str("uv also reads the following externally defined environment variables:\n\n"); + + for (var, doc) in external_vars { + output.push_str(&render(&var, &doc)); } output } +/// Render an environment variable and its documentation. +fn render(var: &str, doc: &str) -> String { + // Remove empty lines and add two spaces to the beginning from the second line. + let doc = doc + .lines() + .filter(|line| !line.trim().is_empty()) + .collect::>() + .join("\n"); + format!("### `{var}`\n\n{doc}\n\n") +} + #[cfg(test)] mod tests; diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index 0d0c1ccd8017c..8c3d6e97f69fb 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -1,191 +1,515 @@ # Environment variables -uv respects the following environment variables: - -- [`UV_DEFAULT_INDEX`](#UV_DEFAULT_INDEX): Equivalent to the `--default-index` command-line argument. If set, uv will use - this URL as the default index when searching for packages. -- [`UV_INDEX`](#UV_INDEX): Equivalent to the `--index` command-line argument. If set, uv will use this - space-separated list of URLs as additional indexes when searching for packages. -- [`UV_INDEX_URL`](#UV_INDEX_URL): Equivalent to the `--index-url` command-line argument. If set, uv will use this - URL as the default index when searching for packages. - (Deprecated: use `UV_DEFAULT_INDEX` instead.) -- [`UV_EXTRA_INDEX_URL`](#UV_EXTRA_INDEX_URL): Equivalent to the `--extra-index-url` command-line argument. If set, uv will - use this space-separated list of URLs as additional indexes when searching for packages. - (Deprecated: use `UV_INDEX` instead.) -- [`UV_FIND_LINKS`](#UV_FIND_LINKS): Equivalent to the `--find-links` command-line argument. If set, uv will use this - comma-separated list of additional locations to search for packages. -- [`UV_CACHE_DIR`](#UV_CACHE_DIR): Equivalent to the `--cache-dir` command-line argument. If set, uv will use this - directory for caching instead of the default cache directory. -- [`UV_NO_CACHE`](#UV_NO_CACHE): Equivalent to the `--no-cache` command-line argument. If set, uv will not use the - cache for any operations. -- [`UV_RESOLUTION`](#UV_RESOLUTION): Equivalent to the `--resolution` command-line argument. For example, if set to - `lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. -- [`UV_PRERELEASE`](#UV_PRERELEASE): Equivalent to the `--prerelease` command-line argument. For example, if set to - `allow`, uv will allow pre-release versions for all dependencies. -- [`UV_SYSTEM_PYTHON`](#UV_SYSTEM_PYTHON): Equivalent to the `--system` command-line argument. If set to `true`, uv will - use the first Python interpreter found in the system `PATH`. - WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) - or containerized environments and should be used with caution, as modifying the system - Python can lead to unexpected behavior. -- [`UV_PYTHON`](#UV_PYTHON): Equivalent to the `--python` command-line argument. If set to a path, uv will use - this Python interpreter for all operations. -- [`UV_BREAK_SYSTEM_PACKAGES`](#UV_BREAK_SYSTEM_PACKAGES): Equivalent to the `--break-system-packages` command-line argument. If set to `true`, - uv will allow the installation of packages that conflict with system-installed packages. - WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration - (CI) or containerized environments and should be used with caution, as modifying the system - Python can lead to unexpected behavior. -- [`UV_NATIVE_TLS`](#UV_NATIVE_TLS): Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will - use the system's trust store instead of the bundled `webpki-roots` crate. -- [`UV_INDEX_STRATEGY`](#UV_INDEX_STRATEGY): Equivalent to the `--index-strategy` command-line argument. For example, if - set to `unsafe-any-match`, uv will consider versions of a given package available across all index - URLs, rather than limiting its search to the first index URL that contains the package. -- [`UV_REQUIRE_HASHES`](#UV_REQUIRE_HASHES): Equivalent to the `--require-hashes` command-line argument. If set to `true`, - uv will require that all dependencies have a hash specified in the requirements file. -- [`UV_CONSTRAINT`](#UV_CONSTRAINT): Equivalent to the `--constraint` command-line argument. If set, uv will use this - file as the constraints file. Uses space-separated list of files. -- [`UV_BUILD_CONSTRAINT`](#UV_BUILD_CONSTRAINT): Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file - as constraints for any source distribution builds. Uses space-separated list of files. -- [`UV_OVERRIDE`](#UV_OVERRIDE): Equivalent to the `--override` command-line argument. If set, uv will use this file - as the overrides file. Uses space-separated list of files. -- [`UV_LINK_MODE`](#UV_LINK_MODE): Equivalent to the `--link-mode` command-line argument. If set, uv will use this as - a link mode. -- [`UV_NO_BUILD_ISOLATION`](#UV_NO_BUILD_ISOLATION): Equivalent to the `--no-build-isolation` command-line argument. If set, uv will - skip isolation when building source distributions. -- [`UV_CUSTOM_COMPILE_COMMAND`](#UV_CUSTOM_COMPILE_COMMAND): Equivalent to the `--custom-compile-command` command-line argument. - Used to override uv in the output header of the `requirements.txt` files generated by - `uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper - script, to include the name of the wrapper script in the output file. -- [`UV_KEYRING_PROVIDER`](#UV_KEYRING_PROVIDER): Equivalent to the `--keyring-provider` command-line argument. If set, uv - will use this value as the keyring provider. -- [`UV_CONFIG_FILE`](#UV_CONFIG_FILE): Equivalent to the `--config-file` command-line argument. Expects a path to a - local `uv.toml` file to use as the configuration file. -- [`UV_NO_CONFIG`](#UV_NO_CONFIG): Equivalent to the `--no-config` command-line argument. If set, uv will not read - any configuration files from the current directory, parent directories, or user configuration - directories. -- [`UV_EXCLUDE_NEWER`](#UV_EXCLUDE_NEWER): Equivalent to the `--exclude-newer` command-line argument. If set, uv will - exclude distributions published after the specified date. -- [`UV_PYTHON_PREFERENCE`](#UV_PYTHON_PREFERENCE): Equivalent to the `--python-preference` command-line argument. Whether uv - should prefer system or managed Python versions. -- [`UV_PYTHON_DOWNLOADS`](#UV_PYTHON_DOWNLOADS): Equivalent to the - [`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the - `--no-python-downloads` option. Whether uv should allow Python downloads. -- [`UV_COMPILE_BYTECODE`](#UV_COMPILE_BYTECODE): Equivalent to the `--compile-bytecode` command-line argument. If set, uv - will compile Python source files to bytecode after installation. -- [`UV_PUBLISH_URL`](#UV_PUBLISH_URL): Equivalent to the `--publish-url` command-line argument. The URL of the upload - endpoint of the index to use with `uv publish`. -- [`UV_PUBLISH_TOKEN`](#UV_PUBLISH_TOKEN): Equivalent to the `--token` command-line argument in `uv publish`. If set, uv - will use this token (with the username `__token__`) for publishing. -- [`UV_PUBLISH_USERNAME`](#UV_PUBLISH_USERNAME): Equivalent to the `--username` command-line argument in `uv publish`. If - set, uv will use this username for publishing. -- [`UV_PUBLISH_PASSWORD`](#UV_PUBLISH_PASSWORD): Equivalent to the `--password` command-line argument in `uv publish`. If - set, uv will use this password for publishing. -- [`UV_PUBLISH_CHECK_URL`](#UV_PUBLISH_CHECK_URL): Don't upload a file if it already exists on the index. The value is the URL of the index. -- [`UV_NO_SYNC`](#UV_NO_SYNC): Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating - the environment. -- [`UV_LOCKED`](#UV_LOCKED): Equivalent to the `--locked` command-line argument. If set, uv will assert that the - `uv.lock` remains unchanged. -- [`UV_FROZEN`](#UV_FROZEN): Equivalent to the `--frozen` command-line argument. If set, uv will run without - updating the `uv.lock` file. -- [`UV_PREVIEW`](#UV_PREVIEW): Equivalent to the `--preview` argument. Enables preview mode. -- [`UV_GITHUB_TOKEN`](#UV_GITHUB_TOKEN): Equivalent to the `--token` argument for self update. A GitHub token for authentication. -- [`UV_VERIFY_HASHES`](#UV_VERIFY_HASHES): Equivalent to the `--verify-hashes` argument. Verifies included hashes. -- [`UV_INSECURE_HOST`](#UV_INSECURE_HOST): Equivalent to the `--allow-insecure-host` argument. -- [`UV_CONCURRENT_DOWNLOADS`](#UV_CONCURRENT_DOWNLOADS): Sets the maximum number of in-flight concurrent downloads that uv will - perform at any given time. -- [`UV_CONCURRENT_BUILDS`](#UV_CONCURRENT_BUILDS): Sets the maximum number of source distributions that uv will build - concurrently at any given time. -- [`UV_CONCURRENT_INSTALLS`](#UV_CONCURRENT_INSTALLS): Controls the number of threads used when installing and unzipping - packages. -- [`UV_NO_PROGRESS`](#UV_NO_PROGRESS): Disables all progress output. For example, spinners and progress bars. -- [`UV_TOOL_DIR`](#UV_TOOL_DIR): Specifies the directory where uv stores managed tools. -- [`UV_TOOL_BIN_DIR`](#UV_TOOL_BIN_DIR): Specifies the "bin" directory for installing tool executables. -- [`UV_PROJECT_ENVIRONMENT`](#UV_PROJECT_ENVIRONMENT): Specifies the path to the directory to use for a project virtual environment. - See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path) - for more details. -- [`UV_PYTHON_BIN_DIR`](#UV_PYTHON_BIN_DIR): Specifies the directory to place links to installed, managed Python executables. -- [`UV_PYTHON_INSTALL_DIR`](#UV_PYTHON_INSTALL_DIR): Specifies the directory for storing managed Python installations. -- [`UV_PYTHON_INSTALL_MIRROR`](#UV_PYTHON_INSTALL_MIRROR): Managed Python installations are downloaded from - [`python-build-standalone`](https://github.com/indygreg/python-build-standalone). - This variable can be set to a mirror URL to use a different source for Python installations. - The provided URL will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g., - `https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`. - Distributions can be read from a local directory by using the `file://` URL scheme. -- [`UV_PYPY_INSTALL_MIRROR`](#UV_PYPY_INSTALL_MIRROR): Managed PyPy installations are downloaded from - [python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a - different source for PyPy installations. The provided URL will replace - `https://downloads.python.org/pypy` in, e.g., - `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`. - Distributions can be read from a local directory by using the `file://` URL scheme. -- [`UV_NO_WRAP`](#UV_NO_WRAP): Use to disable line wrapping for diagnostics. -- [`UV_STACK_SIZE`](#UV_STACK_SIZE): Use to control the stack size used by uv. Typically more relevant for Windows in debug mode. -- [`UV_INDEX_{name}_USERNAME`](#UV_INDEX_{name}_USERNAME): Generates the environment variable key for the HTTP Basic authentication username. -- [`UV_INDEX_{name}_PASSWORD`](#UV_INDEX_{name}_PASSWORD): Generates the environment variable key for the HTTP Basic authentication password. -- [`XDG_CONFIG_DIRS`](#XDG_CONFIG_DIRS): Path to system-level configuration directory on Unix systems. -- [`SYSTEMDRIVE`](#SYSTEMDRIVE): Path to system-level configuration directory on Windows systems. -- [`XDG_CONFIG_HOME`](#XDG_CONFIG_HOME): Path to user-level configuration directory on Unix systems. -- [`XDG_CACHE_HOME`](#XDG_CACHE_HOME): Path to cache directory on Unix systems. -- [`XDG_DATA_HOME`](#XDG_DATA_HOME): Path to directory for storing managed Python installations and tools. -- [`XDG_BIN_HOME`](#XDG_BIN_HOME): Path to directory where executables are installed. -- [`SSL_CERT_FILE`](#SSL_CERT_FILE): Custom certificate bundle file path for SSL connections. -- [`SSL_CLIENT_CERT`](#SSL_CLIENT_CERT): If set, uv will use this file for mTLS authentication. - This should be a single file containing both the certificate and the private key in PEM format. -- [`HTTP_PROXY`](#HTTP_PROXY): Proxy for HTTP requests. -- [`HTTPS_PROXY`](#HTTPS_PROXY): Proxy for HTTPS requests. -- [`ALL_PROXY`](#ALL_PROXY): General proxy for all network requests. -- [`UV_HTTP_TIMEOUT`](#UV_HTTP_TIMEOUT): Timeout (in seconds) for HTTP requests. (default: 30 s) -- [`UV_REQUEST_TIMEOUT`](#UV_REQUEST_TIMEOUT): Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. -- [`HTTP_TIMEOUT`](#HTTP_TIMEOUT): Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. -- [`PYC_INVALIDATION_MODE`](#PYC_INVALIDATION_MODE): The validation modes to use when run with `--compile`. - See [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). -- [`VIRTUAL_ENV`](#VIRTUAL_ENV): Used to detect an activated virtual environment. -- [`CONDA_PREFIX`](#CONDA_PREFIX): Used to detect an activated Conda environment. -- [`CONDA_DEFAULT_ENV`](#CONDA_DEFAULT_ENV): Used to determine if an active Conda environment is the base environment or not. -- [`VIRTUAL_ENV_DISABLE_PROMPT`](#VIRTUAL_ENV_DISABLE_PROMPT): If set to `1` before a virtual environment is activated, then the - virtual environment name will not be prepended to the terminal prompt. -- [`PROMPT`](#PROMPT): Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). -- [`NU_VERSION`](#NU_VERSION): Used to detect `NuShell` usage. -- [`FISH_VERSION`](#FISH_VERSION): Used to detect Fish shell usage. -- [`BASH_VERSION`](#BASH_VERSION): Used to detect Bash shell usage. -- [`ZSH_VERSION`](#ZSH_VERSION): Used to detect Zsh shell usage. -- [`ZDOTDIR`](#ZDOTDIR): Used to determine which `.zshenv` to use when Zsh is being used. -- [`KSH_VERSION`](#KSH_VERSION): Used to detect Ksh shell usage. -- [`MACOSX_DEPLOYMENT_TARGET`](#MACOSX_DEPLOYMENT_TARGET): Used with `--python-platform macos` and related variants to set the - deployment target (i.e., the minimum supported macOS version). - Defaults to `12.0`, the least-recent non-EOL macOS version at time of writing. -- [`NO_COLOR`](#NO_COLOR): Disables colored output (takes precedence over `FORCE_COLOR`). - See [no-color.org](https://no-color.org). -- [`FORCE_COLOR`](#FORCE_COLOR): Forces colored output regardless of terminal support. - See [force-color.org](https://force-color.org). -- [`CLICOLOR_FORCE`](#CLICOLOR_FORCE): Use to control color via `anstyle`. -- [`PATH`](#PATH): The standard `PATH` env var. -- [`HOME`](#HOME): The standard `HOME` env var. -- [`SHELL`](#SHELL): The standard `SHELL` posix env var. -- [`PWD`](#PWD): The standard `PWD` posix env var. -- [`LOCALAPPDATA`](#LOCALAPPDATA): Used to look for Microsoft Store Pythons installations. -- [`GITHUB_ACTIONS`](#GITHUB_ACTIONS): Used for trusted publishing via `uv publish`. -- [`ACTIONS_ID_TOKEN_REQUEST_URL`](#ACTIONS_ID_TOKEN_REQUEST_URL): Used for trusted publishing via `uv publish`. Contains the oidc token url. -- [`ACTIONS_ID_TOKEN_REQUEST_TOKEN`](#ACTIONS_ID_TOKEN_REQUEST_TOKEN): Used for trusted publishing via `uv publish`. Contains the oidc request token. -- [`PYTHONPATH`](#PYTHONPATH): Adds directories to Python module search path (e.g., `PYTHONPATH=/path/to/modules`). -- [`NETRC`](#NETRC): Use to set the .netrc file location. -- [`PAGER`](#PAGER): The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager. -- [`JPY_SESSION_NAME`](#JPY_SESSION_NAME): Used to detect when running inside a Jupyter notebook. -- [`TRACING_DURATIONS_FILE`](#TRACING_DURATIONS_FILE): Use to create the tracing durations file via the `tracing-durations-export` feature. -- [`RUST_LOG`](#RUST_LOG): If set, uv will use this value as the log level for its `--verbose` output. Accepts - any filter compatible with the `tracing_subscriber` crate. - For example: - * `RUST_LOG=uv=debug` is the equivalent of adding `--verbose` to the command line - * `RUST_LOG=trace` will enable trace-level logging. - See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) - for more. -- [`UV_ENV_FILE`](#UV_ENV_FILE): `.env` files from which to load environment variables when executing `uv run` commands. -- [`UV_NO_ENV_FILE`](#UV_NO_ENV_FILE): Ignore `.env` files when executing `uv run` commands. -- [`UV_INSTALLER_GITHUB_BASE_URL`](#UV_INSTALLER_GITHUB_BASE_URL): The URL from which to download uv using the standalone installer and `self update` feature, - in lieu of the default GitHub URL. -- [`UV_INSTALLER_GHE_BASE_URL`](#UV_INSTALLER_GHE_BASE_URL): The URL from which to download uv using the standalone installer and `self update` feature, - in lieu of the default GitHub Enterprise URL. -- [`UV_INSTALL_DIR`](#UV_INSTALL_DIR): The directory in which to install uv using the standalone installer and `self update` feature. - Defaults to `~/.local/bin`. -- [`UV_UNMANAGED_INSTALL`](#UV_UNMANAGED_INSTALL): Used ephemeral environments like CI to install uv to a specific path while preventing - the installer from modifying shell profiles or environment variables. -- [`INSTALLER_NO_MODIFY_PATH`](#INSTALLER_NO_MODIFY_PATH): Avoid modifying the `PATH` environment variable when installing uv using the standalone - installer and `self update` feature. +uv defines and respects the following environment variables: + +### `UV_BREAK_SYSTEM_PACKAGES` + +Equivalent to the `--break-system-packages` command-line argument. If set to `true`, +uv will allow the installation of packages that conflict with system-installed packages. +WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration +(CI) or containerized environments and should be used with caution, as modifying the system +Python can lead to unexpected behavior. + +### `UV_BUILD_CONSTRAINT` + +Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file +as constraints for any source distribution builds. Uses space-separated list of files. + +### `UV_CACHE_DIR` + +Equivalent to the `--cache-dir` command-line argument. If set, uv will use this +directory for caching instead of the default cache directory. + +### `UV_COMPILE_BYTECODE` + +Equivalent to the `--compile-bytecode` command-line argument. If set, uv +will compile Python source files to bytecode after installation. + +### `UV_CONCURRENT_BUILDS` + +Sets the maximum number of source distributions that uv will build +concurrently at any given time. + +### `UV_CONCURRENT_DOWNLOADS` + +Sets the maximum number of in-flight concurrent downloads that uv will +perform at any given time. + +### `UV_CONCURRENT_INSTALLS` + +Controls the number of threads used when installing and unzipping +packages. + +### `UV_CONFIG_FILE` + +Equivalent to the `--config-file` command-line argument. Expects a path to a +local `uv.toml` file to use as the configuration file. + +### `UV_CONSTRAINT` + +Equivalent to the `--constraint` command-line argument. If set, uv will use this +file as the constraints file. Uses space-separated list of files. + +### `UV_CUSTOM_COMPILE_COMMAND` + +Equivalent to the `--custom-compile-command` command-line argument. +Used to override uv in the output header of the `requirements.txt` files generated by +`uv pip compile`. Intended for use-cases in which `uv pip compile` is called from within a wrapper +script, to include the name of the wrapper script in the output file. + +### `UV_DEFAULT_INDEX` + +Equivalent to the `--default-index` command-line argument. If set, uv will use +this URL as the default index when searching for packages. + +### `UV_ENV_FILE` + +`.env` files from which to load environment variables when executing `uv run` commands. + +### `UV_EXCLUDE_NEWER` + +Equivalent to the `--exclude-newer` command-line argument. If set, uv will +exclude distributions published after the specified date. + +### `UV_EXTRA_INDEX_URL` + +Equivalent to the `--extra-index-url` command-line argument. If set, uv will +use this space-separated list of URLs as additional indexes when searching for packages. +(Deprecated: use `UV_INDEX` instead.) + +### `UV_FIND_LINKS` + +Equivalent to the `--find-links` command-line argument. If set, uv will use this +comma-separated list of additional locations to search for packages. + +### `UV_FROZEN` + +Equivalent to the `--frozen` command-line argument. If set, uv will run without +updating the `uv.lock` file. + +### `UV_GITHUB_TOKEN` + +Equivalent to the `--token` argument for self update. A GitHub token for authentication. + +### `UV_HTTP_TIMEOUT` + +Timeout (in seconds) for HTTP requests. (default: 30 s) + +### `UV_INDEX` + +Equivalent to the `--index` command-line argument. If set, uv will use this +space-separated list of URLs as additional indexes when searching for packages. + +### `UV_INDEX_STRATEGY` + +Equivalent to the `--index-strategy` command-line argument. For example, if +set to `unsafe-any-match`, uv will consider versions of a given package available across all index +URLs, rather than limiting its search to the first index URL that contains the package. + +### `UV_INDEX_URL` + +Equivalent to the `--index-url` command-line argument. If set, uv will use this +URL as the default index when searching for packages. +(Deprecated: use `UV_DEFAULT_INDEX` instead.) + +### `UV_INDEX_{name}_PASSWORD` + +Generates the environment variable key for the HTTP Basic authentication password. + +### `UV_INDEX_{name}_USERNAME` + +Generates the environment variable key for the HTTP Basic authentication username. + +### `UV_INSECURE_HOST` + +Equivalent to the `--allow-insecure-host` argument. + +### `UV_INSTALLER_GHE_BASE_URL` + +The URL from which to download uv using the standalone installer and `self update` feature, +in lieu of the default GitHub Enterprise URL. + +### `UV_INSTALLER_GITHUB_BASE_URL` + +The URL from which to download uv using the standalone installer and `self update` feature, +in lieu of the default GitHub URL. + +### `UV_INSTALL_DIR` + +The directory in which to install uv using the standalone installer and `self update` feature. +Defaults to `~/.local/bin`. + +### `UV_KEYRING_PROVIDER` + +Equivalent to the `--keyring-provider` command-line argument. If set, uv +will use this value as the keyring provider. + +### `UV_LINK_MODE` + +Equivalent to the `--link-mode` command-line argument. If set, uv will use this as +a link mode. + +### `UV_LOCKED` + +Equivalent to the `--locked` command-line argument. If set, uv will assert that the +`uv.lock` remains unchanged. + +### `UV_NATIVE_TLS` + +Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will +use the system's trust store instead of the bundled `webpki-roots` crate. + +### `UV_NO_BUILD_ISOLATION` + +Equivalent to the `--no-build-isolation` command-line argument. If set, uv will +skip isolation when building source distributions. + +### `UV_NO_CACHE` + +Equivalent to the `--no-cache` command-line argument. If set, uv will not use the +cache for any operations. + +### `UV_NO_CONFIG` + +Equivalent to the `--no-config` command-line argument. If set, uv will not read +any configuration files from the current directory, parent directories, or user configuration +directories. + +### `UV_NO_ENV_FILE` + +Ignore `.env` files when executing `uv run` commands. + +### `UV_NO_PROGRESS` + +Disables all progress output. For example, spinners and progress bars. + +### `UV_NO_SYNC` + +Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating +the environment. + +### `UV_NO_WRAP` + +Use to disable line wrapping for diagnostics. + +### `UV_OVERRIDE` + +Equivalent to the `--override` command-line argument. If set, uv will use this file +as the overrides file. Uses space-separated list of files. + +### `UV_PRERELEASE` + +Equivalent to the `--prerelease` command-line argument. For example, if set to +`allow`, uv will allow pre-release versions for all dependencies. + +### `UV_PREVIEW` + +Equivalent to the `--preview` argument. Enables preview mode. + +### `UV_PROJECT_ENVIRONMENT` + +Specifies the path to the directory to use for a project virtual environment. +See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path) +for more details. + +### `UV_PUBLISH_CHECK_URL` + +Don't upload a file if it already exists on the index. The value is the URL of the index. + +### `UV_PUBLISH_PASSWORD` + +Equivalent to the `--password` command-line argument in `uv publish`. If +set, uv will use this password for publishing. + +### `UV_PUBLISH_TOKEN` + +Equivalent to the `--token` command-line argument in `uv publish`. If set, uv +will use this token (with the username `__token__`) for publishing. + +### `UV_PUBLISH_URL` + +Equivalent to the `--publish-url` command-line argument. The URL of the upload +endpoint of the index to use with `uv publish`. + +### `UV_PUBLISH_USERNAME` + +Equivalent to the `--username` command-line argument in `uv publish`. If +set, uv will use this username for publishing. + +### `UV_PYPY_INSTALL_MIRROR` + +Managed PyPy installations are downloaded from +[python.org](https://downloads.python.org/). This variable can be set to a mirror URL to use a +different source for PyPy installations. The provided URL will replace +`https://downloads.python.org/pypy` in, e.g., +`https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`. +Distributions can be read from a local directory by using the `file://` URL scheme. + +### `UV_PYTHON` + +Equivalent to the `--python` command-line argument. If set to a path, uv will use +this Python interpreter for all operations. + +### `UV_PYTHON_BIN_DIR` + +Specifies the directory to place links to installed, managed Python executables. + +### `UV_PYTHON_DOWNLOADS` + +Equivalent to the +[`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the +`--no-python-downloads` option. Whether uv should allow Python downloads. + +### `UV_PYTHON_INSTALL_DIR` + +Specifies the directory for storing managed Python installations. + +### `UV_PYTHON_INSTALL_MIRROR` + +Managed Python installations are downloaded from +[`python-build-standalone`](https://github.com/indygreg/python-build-standalone). +This variable can be set to a mirror URL to use a different source for Python installations. +The provided URL will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g., +`https://github.com/indygreg/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`. +Distributions can be read from a local directory by using the `file://` URL scheme. + +### `UV_PYTHON_PREFERENCE` + +Equivalent to the `--python-preference` command-line argument. Whether uv +should prefer system or managed Python versions. + +### `UV_REQUEST_TIMEOUT` + +Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. + +### `UV_REQUIRE_HASHES` + +Equivalent to the `--require-hashes` command-line argument. If set to `true`, +uv will require that all dependencies have a hash specified in the requirements file. + +### `UV_RESOLUTION` + +Equivalent to the `--resolution` command-line argument. For example, if set to +`lowest-direct`, uv will install the lowest compatible versions of all direct dependencies. + +### `UV_STACK_SIZE` + +Use to control the stack size used by uv. Typically more relevant for Windows in debug mode. + +### `UV_SYSTEM_PYTHON` + +Equivalent to the `--system` command-line argument. If set to `true`, uv will +use the first Python interpreter found in the system `PATH`. +WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI) +or containerized environments and should be used with caution, as modifying the system +Python can lead to unexpected behavior. + +### `UV_TOOL_BIN_DIR` + +Specifies the "bin" directory for installing tool executables. + +### `UV_TOOL_DIR` + +Specifies the directory where uv stores managed tools. + +### `UV_UNMANAGED_INSTALL` + +Used ephemeral environments like CI to install uv to a specific path while preventing +the installer from modifying shell profiles or environment variables. + +### `UV_VERIFY_HASHES` + +Equivalent to the `--verify-hashes` argument. Verifies included hashes. + + + +## Externally defined variables + +uv also reads the following externally defined environment variables: + +### `ACTIONS_ID_TOKEN_REQUEST_TOKEN` + +Used for trusted publishing via `uv publish`. Contains the oidc request token. + +### `ACTIONS_ID_TOKEN_REQUEST_URL` + +Used for trusted publishing via `uv publish`. Contains the oidc token url. + +### `ALL_PROXY` + +General proxy for all network requests. + +### `BASH_VERSION` + +Used to detect Bash shell usage. + +### `CLICOLOR_FORCE` + +Use to control color via `anstyle`. + +### `CONDA_DEFAULT_ENV` + +Used to determine if an active Conda environment is the base environment or not. + +### `CONDA_PREFIX` + +Used to detect an activated Conda environment. + +### `FISH_VERSION` + +Used to detect Fish shell usage. + +### `FORCE_COLOR` + +Forces colored output regardless of terminal support. +See [force-color.org](https://force-color.org). + +### `GITHUB_ACTIONS` + +Used for trusted publishing via `uv publish`. + +### `HOME` + +The standard `HOME` env var. + +### `HTTPS_PROXY` + +Proxy for HTTPS requests. + +### `HTTP_PROXY` + +Proxy for HTTP requests. + +### `HTTP_TIMEOUT` + +Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. + +### `INSTALLER_NO_MODIFY_PATH` + +Avoid modifying the `PATH` environment variable when installing uv using the standalone +installer and `self update` feature. + +### `JPY_SESSION_NAME` + +Used to detect when running inside a Jupyter notebook. + +### `KSH_VERSION` + +Used to detect Ksh shell usage. + +### `LOCALAPPDATA` + +Used to look for Microsoft Store Pythons installations. + +### `MACOSX_DEPLOYMENT_TARGET` + +Used with `--python-platform macos` and related variants to set the +deployment target (i.e., the minimum supported macOS version). +Defaults to `12.0`, the least-recent non-EOL macOS version at time of writing. + +### `NETRC` + +Use to set the .netrc file location. + +### `NO_COLOR` + +Disables colored output (takes precedence over `FORCE_COLOR`). +See [no-color.org](https://no-color.org). + +### `NU_VERSION` + +Used to detect `NuShell` usage. + +### `PAGER` + +The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager. + +### `PATH` + +The standard `PATH` env var. + +### `PROMPT` + +Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). + +### `PWD` + +The standard `PWD` posix env var. + +### `PYC_INVALIDATION_MODE` + +The validation modes to use when run with `--compile`. +See [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). + +### `PYTHONPATH` + +Adds directories to Python module search path (e.g., `PYTHONPATH=/path/to/modules`). + +### `RUST_LOG` + +If set, uv will use this value as the log level for its `--verbose` output. Accepts +any filter compatible with the `tracing_subscriber` crate. +For example: +* `RUST_LOG=uv=debug` is the equivalent of adding `--verbose` to the command line +* `RUST_LOG=trace` will enable trace-level logging. +See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax) +for more. + +### `SHELL` + +The standard `SHELL` posix env var. + +### `SSL_CERT_FILE` + +Custom certificate bundle file path for SSL connections. + +### `SSL_CLIENT_CERT` + +If set, uv will use this file for mTLS authentication. +This should be a single file containing both the certificate and the private key in PEM format. + +### `SYSTEMDRIVE` + +Path to system-level configuration directory on Windows systems. + +### `TRACING_DURATIONS_FILE` + +Use to create the tracing durations file via the `tracing-durations-export` feature. + +### `VIRTUAL_ENV` + +Used to detect an activated virtual environment. + +### `VIRTUAL_ENV_DISABLE_PROMPT` + +If set to `1` before a virtual environment is activated, then the +virtual environment name will not be prepended to the terminal prompt. + +### `XDG_BIN_HOME` + +Path to directory where executables are installed. + +### `XDG_CACHE_HOME` + +Path to cache directory on Unix systems. + +### `XDG_CONFIG_DIRS` + +Path to system-level configuration directory on Unix systems. + +### `XDG_CONFIG_HOME` + +Path to user-level configuration directory on Unix systems. + +### `XDG_DATA_HOME` + +Path to directory for storing managed Python installations and tools. + +### `ZDOTDIR` + +Used to determine which `.zshenv` to use when Zsh is being used. + +### `ZSH_VERSION` + +Used to detect Zsh shell usage. +