From 647494b99871ca0ca864484fae9a40a1e21f0f30 Mon Sep 17 00:00:00 2001 From: samypr100 <3933065+samypr100@users.noreply.github.com> Date: Sun, 3 Nov 2024 18:56:17 +0000 Subject: [PATCH] docs: env var doc improvements (#8777) ## Summary * Env docs now support anchors, which allows sending a link to someone with a direct reference to an env var or cross-reference them in the docs. * Marked additional env vars as hidden from the docs due to their internal use * Updates some tests still using literals to use the static env vars ## Test Plan env_var_anchors --- .../uv-dev/src/generate_env_vars_reference.rs | 4 +- crates/uv-static/src/env_vars.rs | 21 +- crates/uv/tests/it/common/mod.rs | 9 +- crates/uv/tests/it/edit.rs | 4 +- crates/uv/tests/it/init.rs | 4 +- crates/uv/tests/it/lock.rs | 4 +- crates/uv/tests/it/pip_compile.rs | 2 +- docs/configuration/environment.md | 213 ++++++++---------- 8 files changed, 130 insertions(+), 131 deletions(-) diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/crates/uv-dev/src/generate_env_vars_reference.rs index 222c49cb9abd..9e6467b01be5 100644 --- a/crates/uv-dev/src/generate_env_vars_reference.rs +++ b/crates/uv-dev/src/generate_env_vars_reference.rs @@ -88,7 +88,9 @@ fn generate() -> String { }) .collect::>() .join("\n"); - output.push_str(&format!("- `{var}`: {doc}\n")); + output.push_str(&format!( + "- [`{var}`](#{var}): {doc}\n" + )); } output diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs index 7f5850b469ee..4719f504729b 100644 --- a/crates/uv-static/src/env_vars.rs +++ b/crates/uv-static/src/env_vars.rs @@ -185,6 +185,9 @@ impl EnvVars { /// packages. pub const UV_CONCURRENT_INSTALLS: &'static str = "UV_CONCURRENT_INSTALLS"; + /// Disables all progress output. For example, spinners and progress bars. + pub const UV_NO_PROGRESS: &'static str = "UV_NO_PROGRESS"; + /// Specifies the directory where uv stores managed tools. pub const UV_TOOL_DIR: &'static str = "UV_TOOL_DIR"; @@ -370,9 +373,6 @@ impl EnvVars { /// See [no-color.org](https://no-color.org). pub const NO_COLOR: &'static str = "NO_COLOR"; - /// Disables all progress output. For example, spinners and progress bars. - pub const UV_NO_PROGRESS: &'static str = "UV_NO_PROGRESS"; - /// Forces colored output regardless of terminal support. /// /// See [force-color.org](https://force-color.org). @@ -397,18 +397,23 @@ impl EnvVars { pub const LOCALAPPDATA: &'static str = "LOCALAPPDATA"; /// Path to the `.git` directory. Ignored by `uv` when performing fetch. + #[attr_hidden] pub const GIT_DIR: &'static str = "GIT_DIR"; /// Path to the git working tree. Ignored by `uv` when performing fetch. + #[attr_hidden] pub const GIT_WORK_TREE: &'static str = "GIT_WORK_TREE"; /// Path to the index file for staged changes. Ignored by `uv` when performing fetch. + #[attr_hidden] pub const GIT_INDEX_FILE: &'static str = "GIT_INDEX_FILE"; /// Path to where git object files are located. Ignored by `uv` when performing fetch. + #[attr_hidden] pub const GIT_OBJECT_DIRECTORY: &'static str = "GIT_OBJECT_DIRECTORY"; /// Alternate locations for git objects. Ignored by `uv` when performing fetch. + #[attr_hidden] pub const GIT_ALTERNATE_OBJECT_DIRECTORIES: &'static str = "GIT_ALTERNATE_OBJECT_DIRECTORIES"; /// Used in tests for better git isolation. @@ -419,6 +424,7 @@ impl EnvVars { /// `GIT_CEILING_DIRECTORIES=/home/andrew/.local/share/uv/tests` will /// prevent git from crawling up the directory tree past that point to find /// parent git repositories. + #[attr_hidden] pub const GIT_CEILING_DIRECTORIES: &'static str = "GIT_CEILING_DIRECTORIES"; /// Used for trusted publishing via `uv publish`. @@ -431,18 +437,26 @@ impl EnvVars { pub const ACTIONS_ID_TOKEN_REQUEST_TOKEN: &'static str = "ACTIONS_ID_TOKEN_REQUEST_TOKEN"; /// Sets the encoding for standard I/O streams (e.g., PYTHONIOENCODING=utf-8). + #[attr_hidden] pub const PYTHONIOENCODING: &'static str = "PYTHONIOENCODING"; /// Forces unbuffered I/O streams, equivalent to `-u` in Python. + #[attr_hidden] pub const PYTHONUNBUFFERED: &'static str = "PYTHONUNBUFFERED"; /// Enables UTF-8 mode for Python, equivalent to `-X utf8`. + #[attr_hidden] pub const PYTHONUTF8: &'static str = "PYTHONUTF8"; /// Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules). pub const PYTHONPATH: &'static str = "PYTHONPATH"; + /// Used in tests to enforce a consistent locale setting. + #[attr_hidden] + pub const LC_ALL: &'static str = "LC_ALL"; + /// Typically set by CI runners, used to detect a CI runner. + #[attr_hidden] pub const CI: &'static str = "CI"; /// Use to set the .netrc file location. @@ -455,6 +469,7 @@ impl EnvVars { pub const JPY_SESSION_NAME: &'static str = "JPY_SESSION_NAME"; /// Use to create the tracing root directory via the `tracing-durations-export` feature. + #[attr_hidden] pub const TRACING_DURATIONS_TEST_ROOT: &'static str = "TRACING_DURATIONS_TEST_ROOT"; /// Use to create the tracing durations file via the `tracing-durations-export` feature. diff --git a/crates/uv/tests/it/common/mod.rs b/crates/uv/tests/it/common/mod.rs index 48ef6c4bc9e5..1d509b8d9037 100644 --- a/crates/uv/tests/it/common/mod.rs +++ b/crates/uv/tests/it/common/mod.rs @@ -478,7 +478,7 @@ impl TestContext { if cfg!(unix) { // Avoid locale issues in tests - command.env("LC_ALL", "C"); + command.env(EnvVars::LC_ALL, "C"); } if cfg!(all(windows, debug_assertions)) { @@ -663,10 +663,9 @@ impl TestContext { .env(EnvVars::UV_PYTHON_BIN_DIR, bin.as_os_str()) .env( EnvVars::PATH, - std::env::join_paths( - std::iter::once(bin) - .chain(std::env::split_paths(&env::var("PATH").unwrap_or_default())), - ) + std::env::join_paths(std::iter::once(bin).chain(std::env::split_paths( + &env::var(EnvVars::PATH).unwrap_or_default(), + ))) .unwrap(), ) .current_dir(&self.temp_dir); diff --git a/crates/uv/tests/it/edit.rs b/crates/uv/tests/it/edit.rs index 397dc53b3767..c93bfec3fbc2 100644 --- a/crates/uv/tests/it/edit.rs +++ b/crates/uv/tests/it/edit.rs @@ -6819,7 +6819,7 @@ fn add_index_credentials() -> Result<()> { "#})?; // Provide credentials for the index via the environment variable. - uv_snapshot!(context.filters(), context.add().arg("iniconfig==2.0.0").env("UV_DEFAULT_INDEX", "https://public:heron@pypi-proxy.fly.dev/basic-auth/simple"), @r###" + uv_snapshot!(context.filters(), context.add().arg("iniconfig==2.0.0").env(EnvVars::UV_DEFAULT_INDEX, "https://public:heron@pypi-proxy.fly.dev/basic-auth/simple"), @r###" success: true exit_code: 0 ----- stdout ----- @@ -6913,7 +6913,7 @@ fn add_index_comments() -> Result<()> { "#})?; // Preserve the comment on the index URL, despite replacing it. - uv_snapshot!(context.filters(), context.add().arg("iniconfig==2.0.0").env("UV_DEFAULT_INDEX", "https://pypi.org/simple"), @r###" + uv_snapshot!(context.filters(), context.add().arg("iniconfig==2.0.0").env(EnvVars::UV_DEFAULT_INDEX, "https://pypi.org/simple"), @r###" success: true exit_code: 0 ----- stdout ----- diff --git a/crates/uv/tests/it/init.rs b/crates/uv/tests/it/init.rs index 5a972fb49161..e56bdda39ab9 100644 --- a/crates/uv/tests/it/init.rs +++ b/crates/uv/tests/it/init.rs @@ -2416,7 +2416,7 @@ fn init_application_package_flit() -> Result<()> { ); }); - uv_snapshot!(context.filters(), context.run().current_dir(&child).env_remove("VIRTUAL_ENV").arg("foo"), @r###" + uv_snapshot!(context.filters(), context.run().current_dir(&child).env_remove(EnvVars::VIRTUAL_ENV).arg("foo"), @r###" success: true exit_code: 0 ----- stdout ----- @@ -2497,7 +2497,7 @@ fn init_library_flit() -> Result<()> { ); }); - uv_snapshot!(context.filters(), context.run().current_dir(&child).env_remove("VIRTUAL_ENV").arg("python").arg("-c").arg("import foo; print(foo.hello())"), @r###" + uv_snapshot!(context.filters(), context.run().current_dir(&child).env_remove(EnvVars::VIRTUAL_ENV).arg("python").arg("-c").arg("import foo; print(foo.hello())"), @r###" success: true exit_code: 0 ----- stdout ----- diff --git a/crates/uv/tests/it/lock.rs b/crates/uv/tests/it/lock.rs index 140206bd9323..10788cb51521 100644 --- a/crates/uv/tests/it/lock.rs +++ b/crates/uv/tests/it/lock.rs @@ -13435,7 +13435,7 @@ fn lock_named_index_cli() -> Result<()> { )?; // The package references a non-existent index. - uv_snapshot!(context.filters(), context.lock().env_remove("UV_EXCLUDE_NEWER"), @r###" + uv_snapshot!(context.filters(), context.lock().env_remove(EnvVars::UV_EXCLUDE_NEWER), @r###" success: false exit_code: 2 ----- stdout ----- @@ -13447,7 +13447,7 @@ fn lock_named_index_cli() -> Result<()> { "###); // But it's fine if it comes from the CLI. - uv_snapshot!(context.filters(), context.lock().arg("--index").arg("pytorch=https://download.pytorch.org/whl/cu121").env_remove("UV_EXCLUDE_NEWER"), @r###" + uv_snapshot!(context.filters(), context.lock().arg("--index").arg("pytorch=https://download.pytorch.org/whl/cu121").env_remove(EnvVars::UV_EXCLUDE_NEWER), @r###" success: true exit_code: 0 ----- stdout ----- diff --git a/crates/uv/tests/it/pip_compile.rs b/crates/uv/tests/it/pip_compile.rs index 07c957911f04..149ed32b29c7 100644 --- a/crates/uv/tests/it/pip_compile.rs +++ b/crates/uv/tests/it/pip_compile.rs @@ -5508,7 +5508,7 @@ fn emit_index_urls() -> Result<()> { .arg("https://test.pypi.org/simple/") .arg("--extra-index-url") .arg("https://pypi.org/simple") - .env("UV_EXTRA_INDEX_URL", "https://pypi.org/simple"), @r###" + .env(EnvVars::UV_EXTRA_INDEX_URL, "https://pypi.org/simple"), @r###" success: true exit_code: 0 ----- stdout ----- diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index bd9206ced7be..8956d56c33de 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -2,191 +2,174 @@ uv respects the following environment variables: -- `UV_DEFAULT_INDEX`: Equivalent to the `--default-index` command-line argument. If set, uv will use +- [`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`: Equivalent to the `--index` command-line argument. If set, uv will use this +- [`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`: Equivalent to the `--index-url` command-line argument. If set, uv will use this +- [`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`: Equivalent to the `--extra-index-url` command-line argument. If set, uv will +- [`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`: Equivalent to the `--find-links` command-line argument. If set, uv will use this +- [`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`: Equivalent to the `--cache-dir` command-line argument. If set, uv will use this +- [`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`: Equivalent to the `--no-cache` command-line argument. If set, uv will not use the +- [`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`: Equivalent to the `--resolution` command-line argument. For example, if set to +- [`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`: Equivalent to the `--prerelease` command-line argument. For example, if set to +- [`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`: Equivalent to the `--system` command-line argument. If set to `true`, uv will +- [`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`: Equivalent to the `--python` command-line argument. If set to a path, uv will use +- [`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`: Equivalent to the `--break-system-packages` command-line argument. If set to `true`, +- [`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`: Equivalent to the `--native-tls` command-line argument. If set to `true`, uv will +- [`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`: Equivalent to the `--index-strategy` command-line argument. For example, if +- [`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`: Equivalent to the `--require-hashes` command-line argument. If set to `true`, +- [`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`: Equivalent to the `--constraint` command-line argument. If set, uv will use this +- [`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`: Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file +- [`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`: Equivalent to the `--override` command-line argument. If set, uv will use this file +- [`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`: Equivalent to the `--link-mode` command-line argument. If set, uv will use this as +- [`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`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will +- [`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`: Equivalent to the `--custom-compile-command` command-line argument. +- [`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`: Equivalent to the `--keyring-provider` command-line argument. If set, uv +- [`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`: Equivalent to the `--config-file` command-line argument. Expects a path to a +- [`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`: Equivalent to the `--no-config` command-line argument. If set, uv will not read +- [`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`: Equivalent to the `--exclude-newer` command-line argument. If set, uv will +- [`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`: Equivalent to the `--python-preference` command-line argument. Whether uv +- [`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`: Equivalent to the +- [`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`: Equivalent to the `--compile-bytecode` command-line argument. If set, uv +- [`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`: Equivalent to the `--publish-url` command-line argument. The URL of the upload +- [`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`: Equivalent to the `--token` command-line argument in `uv publish`. If set, uv +- [`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`: Equivalent to the `--username` command-line argument in `uv publish`. If +- [`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`: Equivalent to the `--password` command-line argument in `uv publish`. If +- [`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`: Don't upload a file if it already exists on the index. The value is the URL of the index. -- `UV_NO_SYNC`: Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating +- [`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`: Equivalent to the `--locked` command-line argument. If set, uv will assert that the +- [`UV_LOCKED`](#UV_LOCKED): Equivalent to the `--locked` command-line argument. If set, uv will assert that the `uv.lock` remains unchanged. -- `UV_FROZEN`: Equivalent to the `--frozen` command-line argument. If set, uv will run without +- [`UV_FROZEN`](#UV_FROZEN): Equivalent to the `--frozen` command-line argument. If set, uv will run without updating the `uv.lock` file. -- `UV_PREVIEW`: Equivalent to the `--preview` argument. Enables preview mode. -- `UV_GITHUB_TOKEN`: Equivalent to the `--token` argument for self update. A GitHub token for authentication. -- `UV_VERIFY_HASHES`: Equivalent to the `--verify-hashes` argument. Verifies included hashes. -- `UV_INSECURE_HOST`: Equivalent to the `--allow-insecure-host` argument. -- `UV_CONCURRENT_DOWNLOADS`: Sets the maximum number of in-flight concurrent downloads that uv will +- [`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`: Sets the maximum number of source distributions that uv will build +- [`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`: Controls the number of threads used when installing and unzipping +- [`UV_CONCURRENT_INSTALLS`](#UV_CONCURRENT_INSTALLS): Controls the number of threads used when installing and unzipping packages. -- `UV_TOOL_DIR`: Specifies the directory where uv stores managed tools. -- `UV_TOOL_BIN_DIR`: Specifies the "bin" directory for installing tool executables. -- `UV_PROJECT_ENVIRONMENT`: Specifies the path to the directory to use for a project virtual environment. +- [`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`: Specifies the directory to place links to installed, managed Python executables. -- `UV_PYTHON_INSTALL_DIR`: Specifies the directory for storing managed Python installations. -- `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from +- [`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`: Managed PyPy installations are downloaded from +- [`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`: Use to disable line wrapping for diagnostics. -- `UV_STACK_SIZE`: Use to control the stack size used by uv. Typically more relevant for Windows in debug mode. -- `UV_INDEX_{name}_USERNAME`: Generates the environment variable key for the HTTP Basic authentication username. -- `UV_INDEX_{name}_PASSWORD`: Generates the environment variable key for the HTTP Basic authentication password. -- `XDG_CONFIG_DIRS`: Path to system-level configuration directory on Unix systems. -- `SYSTEMDRIVE`: Path to system-level configuration directory on Windows systems. -- `XDG_CONFIG_HOME`: Path to user-level configuration directory on Unix systems. -- `XDG_CACHE_HOME`: Path to cache directory on Unix systems. -- `XDG_DATA_HOME`: Path to directory for storing managed Python installations and tools. -- `XDG_BIN_HOME`: Path to directory where executables are installed. -- `SSL_CERT_FILE`: Custom certificate bundle file path for SSL connections. -- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. +- [`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`: Proxy for HTTP requests. -- `HTTPS_PROXY`: Proxy for HTTPS requests. -- `ALL_PROXY`: General proxy for all network requests. -- `UV_HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. (default: 30 s) -- `UV_REQUEST_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. -- `HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. -- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`. +- [`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`: Used to detect an activated virtual environment. -- `CONDA_PREFIX`: Used to detect an activated Conda environment. -- `VIRTUAL_ENV_DISABLE_PROMPT`: If set to `1` before a virtual environment is activated, then the +- [`VIRTUAL_ENV`](#VIRTUAL_ENV): Used to detect an activated virtual environment. +- [`CONDA_PREFIX`](#CONDA_PREFIX): Used to detect an activated Conda environment. +- [`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`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). -- `NU_VERSION`: Used to detect `NuShell` usage. -- `FISH_VERSION`: Used to detect Fish shell usage. -- `BASH_VERSION`: Used to detect Bash shell usage. -- `ZSH_VERSION`: Used to detect Zsh shell usage. -- `ZDOTDIR`: Used to determine which `.zshenv` to use when Zsh is being used. -- `KSH_VERSION`: Used to detect Ksh shell usage. -- `MACOSX_DEPLOYMENT_TARGET`: Used with `--python-platform macos` and related variants to set the +- [`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`: Disables colored output (takes precedence over `FORCE_COLOR`). +- [`NO_COLOR`](#NO_COLOR): Disables colored output (takes precedence over `FORCE_COLOR`). See [no-color.org](https://no-color.org). -- `UV_NO_PROGRESS`: Disables all progress output. For example, spinners and progress bars. -- `FORCE_COLOR`: Forces colored output regardless of terminal support. +- [`FORCE_COLOR`](#FORCE_COLOR): Forces colored output regardless of terminal support. See [force-color.org](https://force-color.org). -- `CLICOLOR_FORCE`: Use to control color via `anstyle`. -- `PATH`: The standard `PATH` env var. -- `HOME`: The standard `HOME` env var. -- `SHELL`: The standard `SHELL` posix env var. -- `PWD`: The standard `PWD` posix env var. -- `LOCALAPPDATA`: Used to look for Microsoft Store Pythons installations. -- `GIT_DIR`: Path to the `.git` directory. Ignored by `uv` when performing fetch. -- `GIT_WORK_TREE`: Path to the git working tree. Ignored by `uv` when performing fetch. -- `GIT_INDEX_FILE`: Path to the index file for staged changes. Ignored by `uv` when performing fetch. -- `GIT_OBJECT_DIRECTORY`: Path to where git object files are located. Ignored by `uv` when performing fetch. -- `GIT_ALTERNATE_OBJECT_DIRECTORIES`: Alternate locations for git objects. Ignored by `uv` when performing fetch. -- `GIT_CEILING_DIRECTORIES`: Used in tests for better git isolation. - For example, we run some tests in ~/.local/share/uv/tests. - And if the user's `$HOME` directory is a git repository, - this will change the behavior of some tests. Setting - `GIT_CEILING_DIRECTORIES=/home/andrew/.local/share/uv/tests` will - prevent git from crawling up the directory tree past that point to find - parent git repositories. -- `GITHUB_ACTIONS`: Used for trusted publishing via `uv publish`. -- `ACTIONS_ID_TOKEN_REQUEST_URL`: Used for trusted publishing via `uv publish`. Contains the oidc token url. -- `ACTIONS_ID_TOKEN_REQUEST_TOKEN`: Used for trusted publishing via `uv publish`. Contains the oidc request token. -- `PYTHONIOENCODING`: Sets the encoding for standard I/O streams (e.g., PYTHONIOENCODING=utf-8). -- `PYTHONUNBUFFERED`: Forces unbuffered I/O streams, equivalent to `-u` in Python. -- `PYTHONUTF8`: Enables UTF-8 mode for Python, equivalent to `-X utf8`. -- `PYTHONPATH`: Adds directories to Python module search path (e.g., PYTHONPATH=/path/to/modules). -- `CI`: Typically set by CI runners, used to detect a CI runner. -- `NETRC`: Use to set the .netrc file location. -- `PAGER`: The standard `PAGER` posix env var. Used by `uv` to configure the appropriate pager. -- `JPY_SESSION_NAME`: Used to detect when running inside a Jupyter notebook. -- `TRACING_DURATIONS_TEST_ROOT`: Use to create the tracing root directory via the `tracing-durations-export` feature. -- `TRACING_DURATIONS_FILE`: Use to create the tracing durations file via the `tracing-durations-export` feature. -- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts +- [`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=trace` will enable trace-level logging. See the [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)