From 3dfedf1fef3a5ad48ae0c2f59a36e25fa32a9aa4 Mon Sep 17 00:00:00 2001 From: Jo <10510431+j178@users.noreply.github.com> Date: Sun, 3 Nov 2024 22:31:38 +0800 Subject: [PATCH] Generate environment variables doc from code (#8493) ## Summary Resolves #8417 I've just begun learning procedural macros, so this PR is more of a proof of concept. It's still a work in progress, and I welcome any assistance or feedback. --- .prettierignore | 1 + Cargo.lock | 3 + crates/uv-dev/src/generate_all.rs | 6 +- crates/uv-dev/src/generate_cli_reference.rs | 1 - .../uv-dev/src/generate_env_vars_reference.rs | 98 ++++++++ .../src/generate_env_vars_reference/tests.rs | 19 ++ crates/uv-dev/src/generate_json_schema.rs | 1 - .../uv-dev/src/generate_options_reference.rs | 1 - crates/uv-dev/src/main.rs | 5 + crates/uv-macros/src/lib.rs | 91 ++++++- crates/uv-static/Cargo.toml | 1 + crates/uv-static/src/env_vars.rs | 222 +++++++++++++----- docs/configuration/environment.md | 177 ++++++++------ 13 files changed, 491 insertions(+), 135 deletions(-) create mode 100644 crates/uv-dev/src/generate_env_vars_reference.rs create mode 100644 crates/uv-dev/src/generate_env_vars_reference/tests.rs diff --git a/.prettierignore b/.prettierignore index 4d9c0f248fef..dc54f51fffd7 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,5 +3,6 @@ CHANGELOG.md PREVIEW-CHANGELOG.md docs/reference/cli.md docs/reference/settings.md +docs/configuration/environment.md ecosystem/home-assistant-core/LICENSE.md docs/guides/integration/gitlab.md diff --git a/Cargo.lock b/Cargo.lock index a1aa322c9cc9..dac95ce94b43 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -5264,6 +5264,9 @@ dependencies = [ [[package]] name = "uv-static" version = "0.0.1" +dependencies = [ + "uv-macros", +] [[package]] name = "uv-tool" diff --git a/crates/uv-dev/src/generate_all.rs b/crates/uv-dev/src/generate_all.rs index 74a4261cbefa..1655f9a21dde 100644 --- a/crates/uv-dev/src/generate_all.rs +++ b/crates/uv-dev/src/generate_all.rs @@ -2,7 +2,10 @@ use anyhow::Result; -use crate::{generate_cli_reference, generate_json_schema, generate_options_reference}; +use crate::{ + generate_cli_reference, generate_env_vars_reference, generate_json_schema, + generate_options_reference, +}; #[derive(clap::Args)] pub(crate) struct Args { @@ -27,5 +30,6 @@ pub(crate) fn main(args: &Args) -> Result<()> { generate_json_schema::main(&generate_json_schema::Args { mode: args.mode })?; generate_options_reference::main(&generate_options_reference::Args { mode: args.mode })?; generate_cli_reference::main(&generate_cli_reference::Args { mode: args.mode })?; + generate_env_vars_reference::main(&generate_env_vars_reference::Args { mode: args.mode })?; Ok(()) } diff --git a/crates/uv-dev/src/generate_cli_reference.rs b/crates/uv-dev/src/generate_cli_reference.rs index 484ddf7569e6..ec9a2eff5ccb 100644 --- a/crates/uv-dev/src/generate_cli_reference.rs +++ b/crates/uv-dev/src/generate_cli_reference.rs @@ -31,7 +31,6 @@ const SHOW_HIDDEN_COMMANDS: &[&str] = &["generate-shell-completion"]; #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `settings.md`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/generate_env_vars_reference.rs b/crates/uv-dev/src/generate_env_vars_reference.rs new file mode 100644 index 000000000000..222c49cb9abd --- /dev/null +++ b/crates/uv-dev/src/generate_env_vars_reference.rs @@ -0,0 +1,98 @@ +//! Generate the environment variables reference from `uv_static::EnvVars`. + +use anyhow::bail; +use pretty_assertions::StrComparison; +use std::path::PathBuf; + +use uv_static::EnvVars; + +use crate::generate_all::Mode; +use crate::ROOT_DIR; + +#[derive(clap::Args)] +pub(crate) struct Args { + #[arg(long, default_value_t, value_enum)] + pub(crate) mode: Mode, +} + +pub(crate) fn main(args: &Args) -> anyhow::Result<()> { + let reference_string = generate(); + let filename = "environment.md"; + let reference_path = PathBuf::from(ROOT_DIR) + .join("docs") + .join("configuration") + .join(filename); + + match args.mode { + Mode::DryRun => { + anstream::println!("{reference_string}"); + } + Mode::Check => match fs_err::read_to_string(reference_path) { + Ok(current) => { + if current == reference_string { + anstream::println!("Up-to-date: {filename}"); + } else { + let comparison = StrComparison::new(¤t, &reference_string); + bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{comparison}"); + } + } + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + bail!("{filename} not found, please run `cargo dev generate-env-vars-reference`"); + } + Err(err) => { + bail!( + "{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}" + ); + } + }, + Mode::Write => match fs_err::read_to_string(&reference_path) { + Ok(current) => { + if current == reference_string { + anstream::println!("Up-to-date: {filename}"); + } else { + anstream::println!("Updating: {filename}"); + fs_err::write(reference_path, reference_string.as_bytes())?; + } + } + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + anstream::println!("Updating: {filename}"); + fs_err::write(reference_path, reference_string.as_bytes())?; + } + Err(err) => { + bail!("{filename} changed, please run `cargo dev generate-env-vars-reference`:\n{err}"); + } + }, + } + + Ok(()) +} + +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}`: {doc}\n")); + } + + output +} + +#[cfg(test)] +mod tests; diff --git a/crates/uv-dev/src/generate_env_vars_reference/tests.rs b/crates/uv-dev/src/generate_env_vars_reference/tests.rs new file mode 100644 index 000000000000..896fb0ecdd4e --- /dev/null +++ b/crates/uv-dev/src/generate_env_vars_reference/tests.rs @@ -0,0 +1,19 @@ +use std::env; + +use anyhow::Result; + +use uv_static::EnvVars; + +use crate::generate_all::Mode; + +use super::{main, Args}; + +#[test] +fn test_generate_env_vars_reference() -> Result<()> { + let mode = if env::var(EnvVars::UV_UPDATE_SCHEMA).as_deref() == Ok("1") { + Mode::Write + } else { + Mode::Check + }; + main(&Args { mode }) +} diff --git a/crates/uv-dev/src/generate_json_schema.rs b/crates/uv-dev/src/generate_json_schema.rs index 50a89de18ad3..fcf112587ca4 100644 --- a/crates/uv-dev/src/generate_json_schema.rs +++ b/crates/uv-dev/src/generate_json_schema.rs @@ -27,7 +27,6 @@ struct CombinedOptions { #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `uv.schema.json`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/generate_options_reference.rs b/crates/uv-dev/src/generate_options_reference.rs index 3904e030d9b2..2f97cca5c61a 100644 --- a/crates/uv-dev/src/generate_options_reference.rs +++ b/crates/uv-dev/src/generate_options_reference.rs @@ -34,7 +34,6 @@ struct CombinedOptions { #[derive(clap::Args)] pub(crate) struct Args { - /// Write the generated output to stdout (rather than to `settings.md`). #[arg(long, default_value_t, value_enum)] pub(crate) mode: Mode, } diff --git a/crates/uv-dev/src/main.rs b/crates/uv-dev/src/main.rs index b296edb11f89..a46626d42f39 100644 --- a/crates/uv-dev/src/main.rs +++ b/crates/uv-dev/src/main.rs @@ -20,6 +20,7 @@ use crate::clear_compile::ClearCompileArgs; use crate::compile::CompileArgs; use crate::generate_all::Args as GenerateAllArgs; use crate::generate_cli_reference::Args as GenerateCliReferenceArgs; +use crate::generate_env_vars_reference::Args as GenerateEnvVarsReferenceArgs; use crate::generate_json_schema::Args as GenerateJsonSchemaArgs; use crate::generate_options_reference::Args as GenerateOptionsReferenceArgs; #[cfg(feature = "render")] @@ -31,6 +32,7 @@ mod clear_compile; mod compile; mod generate_all; mod generate_cli_reference; +mod generate_env_vars_reference; mod generate_json_schema; mod generate_options_reference; mod render_benchmarks; @@ -54,6 +56,8 @@ enum Cli { GenerateOptionsReference(GenerateOptionsReferenceArgs), /// Generate the CLI reference for the documentation. GenerateCliReference(GenerateCliReferenceArgs), + /// Generate the environment variables reference for the documentation. + GenerateEnvVarsReference(GenerateEnvVarsReferenceArgs), #[cfg(feature = "render")] /// Render the benchmarks. RenderBenchmarks(RenderBenchmarksArgs), @@ -70,6 +74,7 @@ async fn run() -> Result<()> { Cli::GenerateJSONSchema(args) => generate_json_schema::main(&args)?, Cli::GenerateOptionsReference(args) => generate_options_reference::main(&args)?, Cli::GenerateCliReference(args) => generate_cli_reference::main(&args)?, + Cli::GenerateEnvVarsReference(args) => generate_env_vars_reference::main(&args)?, #[cfg(feature = "render")] Cli::RenderBenchmarks(args) => render_benchmarks::render_benchmarks(&args)?, } diff --git a/crates/uv-macros/src/lib.rs b/crates/uv-macros/src/lib.rs index d9db61f3daa0..c2fadad2c4f8 100644 --- a/crates/uv-macros/src/lib.rs +++ b/crates/uv-macros/src/lib.rs @@ -2,7 +2,7 @@ mod options_metadata; use proc_macro::TokenStream; use quote::quote; -use syn::{parse_macro_input, DeriveInput}; +use syn::{parse_macro_input, Attribute, DeriveInput, ImplItem, ItemImpl, LitStr}; #[proc_macro_derive(OptionsMetadata, attributes(option, doc, option_group))] pub fn derive_options_metadata(input: TokenStream) -> TokenStream { @@ -49,3 +49,92 @@ fn impl_combine(ast: &DeriveInput) -> TokenStream { }; gen.into() } + +fn get_doc_comment(attrs: &[Attribute]) -> String { + attrs + .iter() + .filter_map(|attr| { + if attr.path().is_ident("doc") { + if let syn::Meta::NameValue(meta) = &attr.meta { + if let syn::Expr::Lit(expr) = &meta.value { + if let syn::Lit::Str(str) = &expr.lit { + return Some(str.value().trim().to_string()); + } + } + } + } + None + }) + .collect::>() + .join("\n") +} + +fn get_env_var_pattern_from_attr(attrs: &[Attribute]) -> Option { + attrs + .iter() + .find(|attr| attr.path().is_ident("attr_env_var_pattern")) + .and_then(|attr| attr.parse_args::().ok()) + .map(|lit_str| lit_str.value()) +} + +fn is_hidden(attrs: &[Attribute]) -> bool { + attrs.iter().any(|attr| attr.path().is_ident("attr_hidden")) +} + +/// This attribute is used to generate environment variables metadata for [`uv_static::EnvVars`]. +#[proc_macro_attribute] +pub fn attribute_env_vars_metadata(_attr: TokenStream, input: TokenStream) -> TokenStream { + let ast = parse_macro_input!(input as ItemImpl); + + let constants: Vec<_> = ast + .items + .iter() + .filter_map(|item| match item { + ImplItem::Const(item) if !is_hidden(&item.attrs) => { + let name = item.ident.to_string(); + let doc = get_doc_comment(&item.attrs); + Some((name, doc)) + } + ImplItem::Fn(item) if !is_hidden(&item.attrs) => { + // Extract the environment variable patterns. + if let Some(pattern) = get_env_var_pattern_from_attr(&item.attrs) { + let doc = get_doc_comment(&item.attrs); + Some((pattern, doc)) + } else { + None // Skip if pattern extraction fails. + } + } + _ => None, + }) + .collect(); + + let struct_name = &ast.self_ty; + let pairs = constants.iter().map(|(name, doc)| { + quote! { + (#name, #doc) + } + }); + + let expanded = quote! { + #ast + + impl #struct_name { + /// Returns a list of pairs of env var and their documentation defined in this impl block. + pub fn metadata<'a>() -> &'a [(&'static str, &'static str)] { + &[#(#pairs),*] + } + } + }; + + expanded.into() +} + +#[proc_macro_attribute] +pub fn attr_hidden(_attr: TokenStream, item: TokenStream) -> TokenStream { + item +} + +#[proc_macro_attribute] +pub fn attr_env_var_pattern(_attr: TokenStream, item: TokenStream) -> TokenStream { + item +} diff --git a/crates/uv-static/Cargo.toml b/crates/uv-static/Cargo.toml index b054021e6759..77d1fe54b2c1 100644 --- a/crates/uv-static/Cargo.toml +++ b/crates/uv-static/Cargo.toml @@ -16,3 +16,4 @@ doctest = false workspace = true [dependencies] +uv-macros = { workspace = true } diff --git a/crates/uv-static/src/env_vars.rs b/crates/uv-static/src/env_vars.rs index e08681aefdb1..7f5850b469ee 100644 --- a/crates/uv-static/src/env_vars.rs +++ b/crates/uv-static/src/env_vars.rs @@ -1,117 +1,164 @@ +use uv_macros::{attr_env_var_pattern, attr_hidden, attribute_env_vars_metadata}; + /// Declares all environment variable used throughout `uv` and its crates. pub struct EnvVars; +#[attribute_env_vars_metadata] impl EnvVars { - /// Equivalent to the `--default-index` argument. Base index URL for searching packages. + /// Equivalent to the `--default-index` command-line argument. If set, uv will use + /// this URL as the default index when searching for packages. pub const UV_DEFAULT_INDEX: &'static str = "UV_DEFAULT_INDEX"; - /// Equivalent to the `--index` argument. Additional indexes for searching packages. + /// 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. pub const UV_INDEX: &'static str = "UV_INDEX"; - /// Equivalent to the `--index-url` argument. Base index URL for searching packages. - /// - /// Deprecated: use `UV_DEFAULT_INDEX` instead. + /// 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.) pub const UV_INDEX_URL: &'static str = "UV_INDEX_URL"; - /// Equivalent to the `--extra-index-url` argument. Additional indexes for searching packages. - /// - /// Deprecated: use `UV_INDEX` instead. + /// 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.) pub const UV_EXTRA_INDEX_URL: &'static str = "UV_EXTRA_INDEX_URL"; - /// Equivalent to the `--find-links` argument. Additional package search locations. + /// Equivalent to the `--find-links` command-line argument. If set, uv will use this + /// comma-separated list of additional locations to search for packages. pub const UV_FIND_LINKS: &'static str = "UV_FIND_LINKS"; - /// Equivalent to the `--cache-dir` argument. Custom directory for caching. + /// Equivalent to the `--cache-dir` command-line argument. If set, uv will use this + /// directory for caching instead of the default cache directory. pub const UV_CACHE_DIR: &'static str = "UV_CACHE_DIR"; - /// Equivalent to the `--no-cache` argument. Disables cache usage. + /// Equivalent to the `--no-cache` command-line argument. If set, uv will not use the + /// cache for any operations. pub const UV_NO_CACHE: &'static str = "UV_NO_CACHE"; - /// Equivalent to the `--resolution` argument. Controls dependency resolution strategy. + /// 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. pub const UV_RESOLUTION: &'static str = "UV_RESOLUTION"; - /// Equivalent to the `--prerelease` argument. Allows or disallows pre-release versions. + /// Equivalent to the `--prerelease` command-line argument. For example, if set to + /// `allow`, uv will allow pre-release versions for all dependencies. pub const UV_PRERELEASE: &'static str = "UV_PRERELEASE"; - /// Equivalent to the `--system` argument. Use system Python interpreter. + /// 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. pub const UV_SYSTEM_PYTHON: &'static str = "UV_SYSTEM_PYTHON"; - /// Equivalent to the `--python` argument. Path to a specific Python interpreter. + /// Equivalent to the `--python` command-line argument. If set to a path, uv will use + /// this Python interpreter for all operations. pub const UV_PYTHON: &'static str = "UV_PYTHON"; - /// Equivalent to the `--break-system-packages` argument. Allows breaking 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. pub const UV_BREAK_SYSTEM_PACKAGES: &'static str = "UV_BREAK_SYSTEM_PACKAGES"; - /// Equivalent to the `--native-tls` argument. Uses system's trust store for 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. pub const UV_NATIVE_TLS: &'static str = "UV_NATIVE_TLS"; - /// Equivalent to the `--index-strategy` argument. Defines strategy for searching index URLs. + /// 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. pub const UV_INDEX_STRATEGY: &'static str = "UV_INDEX_STRATEGY"; - /// Equivalent to the `--require-hashes` argument. Requires hashes for all dependencies. + /// 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. pub const UV_REQUIRE_HASHES: &'static str = "UV_REQUIRE_HASHES"; - /// Equivalent to the `--constraint` argument. Path to constraints file. + /// Equivalent to the `--constraint` command-line argument. If set, uv will use this + /// file as the constraints file. Uses space-separated list of files. pub const UV_CONSTRAINT: &'static str = "UV_CONSTRAINT"; - /// Equivalent to the `--build-constraint` argument. Path to build constraints file. + /// 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. pub const UV_BUILD_CONSTRAINT: &'static str = "UV_BUILD_CONSTRAINT"; - /// Equivalent to the `--override` argument. Path to overrides file. + /// Equivalent to the `--override` command-line argument. If set, uv will use this file + /// as the overrides file. Uses space-separated list of files. pub const UV_OVERRIDE: &'static str = "UV_OVERRIDE"; - /// Equivalent to the `--link-mode` argument. Specifies link mode for the installation. + /// Equivalent to the `--link-mode` command-line argument. If set, uv will use this as + /// a link mode. pub const UV_LINK_MODE: &'static str = "UV_LINK_MODE"; - /// Equivalent to the `--no-build-isolation` argument. Skips build isolation. + /// Equivalent to the `--no-build-isolation` command-line argument. If set, uv will + /// skip isolation when building source distributions. pub const UV_NO_BUILD_ISOLATION: &'static str = "UV_NO_BUILD_ISOLATION"; - /// Equivalent to the `--custom-compile-command` argument. Overrides the command in `requirements.txt`. + /// 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. pub const UV_CUSTOM_COMPILE_COMMAND: &'static str = "UV_CUSTOM_COMPILE_COMMAND"; - /// Equivalent to the `--keyring-provider` argument. Specifies keyring provider. + /// Equivalent to the `--keyring-provider` command-line argument. If set, uv + /// will use this value as the keyring provider. pub const UV_KEYRING_PROVIDER: &'static str = "UV_KEYRING_PROVIDER"; - /// Equivalent to the `--config-file` argument. Path to configuration file. + /// Equivalent to the `--config-file` command-line argument. Expects a path to a + /// local `uv.toml` file to use as the configuration file. pub const UV_CONFIG_FILE: &'static str = "UV_CONFIG_FILE"; - /// Equivalent to the `--no-config` argument. Prevents reading configuration files. + /// 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. pub const UV_NO_CONFIG: &'static str = "UV_NO_CONFIG"; - /// Equivalent to the `--exclude-newer` argument. Excludes newer distributions after a date. + /// Equivalent to the `--exclude-newer` command-line argument. If set, uv will + /// exclude distributions published after the specified date. pub const UV_EXCLUDE_NEWER: &'static str = "UV_EXCLUDE_NEWER"; - /// Equivalent to the `--python-preference` argument. Controls preference for Python versions. + /// Equivalent to the `--python-preference` command-line argument. Whether uv + /// should prefer system or managed Python versions. pub const UV_PYTHON_PREFERENCE: &'static str = "UV_PYTHON_PREFERENCE"; - /// Equivalent to the `--no-python-downloads` argument. Disables 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. pub const UV_PYTHON_DOWNLOADS: &'static str = "UV_PYTHON_DOWNLOADS"; - /// Equivalent to the `--compile-bytecode` argument. Compiles Python source to bytecode. + /// Equivalent to the `--compile-bytecode` command-line argument. If set, uv + /// will compile Python source files to bytecode after installation. pub const UV_COMPILE_BYTECODE: &'static str = "UV_COMPILE_BYTECODE"; - /// Equivalent to the `--publish-url` argument. URL for publishing packages. + /// Equivalent to the `--publish-url` command-line argument. The URL of the upload + /// endpoint of the index to use with `uv publish`. pub const UV_PUBLISH_URL: &'static str = "UV_PUBLISH_URL"; - /// Equivalent to the `--token` argument in `uv publish`. Token for publishing. + /// Equivalent to the `--token` command-line argument in `uv publish`. If set, uv + /// will use this token (with the username `__token__`) for publishing. pub const UV_PUBLISH_TOKEN: &'static str = "UV_PUBLISH_TOKEN"; - /// Equivalent to the `--username` argument in `uv publish`. Username for publishing. + /// Equivalent to the `--username` command-line argument in `uv publish`. If + /// set, uv will use this username for publishing. pub const UV_PUBLISH_USERNAME: &'static str = "UV_PUBLISH_USERNAME"; - /// Equivalent to the `--password` argument in `uv publish`. Password for publishing. + /// Equivalent to the `--password` command-line argument in `uv publish`. If + /// set, uv will use this password for publishing. pub const UV_PUBLISH_PASSWORD: &'static str = "UV_PUBLISH_PASSWORD"; /// Don't upload a file if it already exists on the index. The value is the URL of the index. pub const UV_PUBLISH_CHECK_URL: &'static str = "UV_PUBLISH_CHECK_URL"; - /// Equivalent to the `--no-sync` argument. Skips syncing the environment. + /// Equivalent to the `--no-sync` command-line argument. If set, uv will skip updating + /// the environment. pub const UV_NO_SYNC: &'static str = "UV_NO_SYNC"; - /// Equivalent to the `--locked` argument. Assert that the `uv.lock` will remain unchanged. + /// Equivalent to the `--locked` command-line argument. If set, uv will assert that the + /// `uv.lock` remains unchanged. pub const UV_LOCKED: &'static str = "UV_LOCKED"; - /// Equivalent to the `--frozen` argument. Run without updating the `uv.lock` file. + /// Equivalent to the `--frozen` command-line argument. If set, uv will run without + /// updating the `uv.lock` file. pub const UV_FROZEN: &'static str = "UV_FROZEN"; /// Equivalent to the `--preview` argument. Enables preview mode. @@ -126,22 +173,27 @@ impl EnvVars { /// Equivalent to the `--allow-insecure-host` argument. pub const UV_INSECURE_HOST: &'static str = "UV_INSECURE_HOST"; - /// Sets the maximum number of in-flight concurrent downloads. + /// Sets the maximum number of in-flight concurrent downloads that uv will + /// perform at any given time. pub const UV_CONCURRENT_DOWNLOADS: &'static str = "UV_CONCURRENT_DOWNLOADS"; - /// Sets the maximum number of concurrent builds for source distributions. + /// Sets the maximum number of source distributions that uv will build + /// concurrently at any given time. pub const UV_CONCURRENT_BUILDS: &'static str = "UV_CONCURRENT_BUILDS"; - /// Controls the number of threads used for concurrent installations. + /// Controls the number of threads used when installing and unzipping + /// packages. pub const UV_CONCURRENT_INSTALLS: &'static str = "UV_CONCURRENT_INSTALLS"; - /// Specifies the directory where `uv` stores managed tools. + /// Specifies the directory where uv stores managed tools. pub const UV_TOOL_DIR: &'static str = "UV_TOOL_DIR"; /// Specifies the "bin" directory for installing tool executables. pub const UV_TOOL_BIN_DIR: &'static str = "UV_TOOL_BIN_DIR"; - /// Specifies the path to the project virtual 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. pub const UV_PROJECT_ENVIRONMENT: &'static str = "UV_PROJECT_ENVIRONMENT"; /// Specifies the directory to place links to installed, managed Python executables. @@ -150,19 +202,32 @@ impl EnvVars { /// Specifies the directory for storing managed Python installations. pub const UV_PYTHON_INSTALL_DIR: &'static str = "UV_PYTHON_INSTALL_DIR"; - /// Mirror URL for downloading managed Python installations. + /// 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. pub const UV_PYTHON_INSTALL_MIRROR: &'static str = "UV_PYTHON_INSTALL_MIRROR"; - /// Mirror URL for downloading managed PyPy installations. + /// 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. pub const UV_PYPY_INSTALL_MIRROR: &'static str = "UV_PYPY_INSTALL_MIRROR"; /// Used to override `PATH` to limit Python executable availability in the test suite. + #[attr_hidden] pub const UV_TEST_PYTHON_PATH: &'static str = "UV_TEST_PYTHON_PATH"; /// Include resolver and installer output related to environment modifications. + #[attr_hidden] pub const UV_SHOW_RESOLUTION: &'static str = "UV_SHOW_RESOLUTION"; /// Use to update the json schema files. + #[attr_hidden] pub const UV_UPDATE_SCHEMA: &'static str = "UV_UPDATE_SCHEMA"; /// Use to disable line wrapping for diagnostics. @@ -172,37 +237,47 @@ impl EnvVars { pub const UV_STACK_SIZE: &'static str = "UV_STACK_SIZE"; /// Generates the environment variable key for the HTTP Basic authentication username. + #[attr_env_var_pattern("UV_INDEX_{name}_USERNAME")] pub fn index_username(name: &str) -> String { format!("UV_INDEX_{name}_USERNAME") } /// Generates the environment variable key for the HTTP Basic authentication password. + #[attr_env_var_pattern("UV_INDEX_{name}_PASSWORD")] pub fn index_password(name: &str) -> String { format!("UV_INDEX_{name}_PASSWORD") } /// Used to set the uv commit hash at build time via `build.rs`. + #[attr_hidden] pub const UV_COMMIT_HASH: &'static str = "UV_COMMIT_HASH"; /// Used to set the uv commit short hash at build time via `build.rs`. + #[attr_hidden] pub const UV_COMMIT_SHORT_HASH: &'static str = "UV_COMMIT_SHORT_HASH"; /// Used to set the uv commit date at build time via `build.rs`. + #[attr_hidden] pub const UV_COMMIT_DATE: &'static str = "UV_COMMIT_DATE"; /// Used to set the uv tag at build time via `build.rs`. + #[attr_hidden] pub const UV_LAST_TAG: &'static str = "UV_LAST_TAG"; /// Used to set the uv tag distance from head at build time via `build.rs`. + #[attr_hidden] pub const UV_LAST_TAG_DISTANCE: &'static str = "UV_LAST_TAG_DISTANCE"; /// Used to set the spawning/parent interpreter when using --system in the test suite. + #[attr_hidden] pub const UV_INTERNAL__PARENT_INTERPRETER: &'static str = "UV_INTERNAL__PARENT_INTERPRETER"; /// Used to force showing the derivation tree during resolver error reporting. + #[attr_hidden] pub const UV_INTERNAL__SHOW_DERIVATION_TREE: &'static str = "UV_INTERNAL__SHOW_DERIVATION_TREE"; /// Used to set a temporary directory for some tests. + #[attr_hidden] pub const UV_INTERNAL__TEST_DIR: &'static str = "UV_INTERNAL__TEST_DIR"; /// Path to system-level configuration directory on Unix systems. @@ -223,19 +298,11 @@ impl EnvVars { /// Path to directory where executables are installed. pub const XDG_BIN_HOME: &'static str = "XDG_BIN_HOME"; - /// Timeout (in seconds) for HTTP requests. - pub const UV_HTTP_TIMEOUT: &'static str = "UV_HTTP_TIMEOUT"; - - /// Timeout (in seconds) for HTTP requests. - pub const UV_REQUEST_TIMEOUT: &'static str = "UV_REQUEST_TIMEOUT"; - - /// Timeout (in seconds) for HTTP requests. - pub const HTTP_TIMEOUT: &'static str = "HTTP_TIMEOUT"; - /// Custom certificate bundle file path for SSL connections. pub const SSL_CERT_FILE: &'static str = "SSL_CERT_FILE"; - /// File for mTLS authentication (contains certificate and private key). + /// 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. pub const SSL_CLIENT_CERT: &'static str = "SSL_CLIENT_CERT"; /// Proxy for HTTP requests. @@ -247,16 +314,31 @@ impl EnvVars { /// General proxy for all network requests. pub const ALL_PROXY: &'static str = "ALL_PROXY"; + /// Timeout (in seconds) for HTTP requests. (default: 30 s) + pub const UV_HTTP_TIMEOUT: &'static str = "UV_HTTP_TIMEOUT"; + + /// Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. + pub const UV_REQUEST_TIMEOUT: &'static str = "UV_REQUEST_TIMEOUT"; + + /// Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`. + pub const HTTP_TIMEOUT: &'static str = "HTTP_TIMEOUT"; + + /// The validation modes to use when run with `--compile`. + /// + /// See [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode). + pub const PYC_INVALIDATION_MODE: &'static str = "PYC_INVALIDATION_MODE"; + /// Used to detect an activated virtual environment. pub const VIRTUAL_ENV: &'static str = "VIRTUAL_ENV"; /// Used to detect an activated Conda environment. pub const CONDA_PREFIX: &'static str = "CONDA_PREFIX"; - /// Disables prepending virtual environment name to the terminal prompt. + /// If set to `1` before a virtual environment is activated, then the + /// virtual environment name will not be prepended to the terminal prompt. pub const VIRTUAL_ENV_DISABLE_PROMPT: &'static str = "VIRTUAL_ENV_DISABLE_PROMPT"; - /// Used to detect Windows Command Prompt usage. + /// Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). pub const PROMPT: &'static str = "PROMPT"; /// Used to detect `NuShell` usage. @@ -277,16 +359,23 @@ impl EnvVars { /// Used to detect Ksh shell usage. pub const KSH_VERSION: &'static str = "KSH_VERSION"; - /// Sets macOS deployment target when using `--python-platform macos`. + /// 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. pub const MACOSX_DEPLOYMENT_TARGET: &'static str = "MACOSX_DEPLOYMENT_TARGET"; /// Disables colored output (takes precedence over `FORCE_COLOR`). + /// + /// 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). pub const FORCE_COLOR: &'static str = "FORCE_COLOR"; /// Use to control color via `anstyle`. @@ -372,34 +461,47 @@ impl EnvVars { pub const TRACING_DURATIONS_FILE: &'static str = "TRACING_DURATIONS_FILE"; /// Used to set `RUST_HOST_TARGET` at build time via `build.rs`. + #[attr_hidden] pub const TARGET: &'static str = "TARGET"; - /// Custom log level for verbose output, compatible with `tracing_subscriber`. + /// 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) + /// for more. pub const RUST_LOG: &'static str = "RUST_LOG"; /// The directory containing the `Cargo.toml` manifest for a package. + #[attr_hidden] pub const CARGO_MANIFEST_DIR: &'static str = "CARGO_MANIFEST_DIR"; /// Specifies the directory where Cargo stores build artifacts (target directory). + #[attr_hidden] pub const CARGO_TARGET_DIR: &'static str = "CARGO_TARGET_DIR"; /// Used in tests for environment substitution testing in `requirements.in`. + #[attr_hidden] pub const URL: &'static str = "URL"; /// Used in tests for environment substitution testing in `requirements.in`. + #[attr_hidden] pub const FILE_PATH: &'static str = "FILE_PATH"; /// Used in tests for environment substitution testing in `requirements.in`. + #[attr_hidden] pub const HATCH_PATH: &'static str = "HATCH_PATH"; /// Used in tests for environment substitution testing in `requirements.in`. + #[attr_hidden] pub const BLACK_PATH: &'static str = "BLACK_PATH"; /// Used in testing Hatch's root.uri feature /// /// See: . + #[attr_hidden] pub const ROOT_PATH: &'static str = "ROOT_PATH"; /// Used to set test credentials for keyring tests. + #[attr_hidden] pub const KEYRING_TEST_CREDENTIALS: &'static str = "KEYRING_TEST_CREDENTIALS"; } diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md index f6c9178c1e1e..bd9206ced7be 100644 --- a/docs/configuration/environment.md +++ b/docs/configuration/environment.md @@ -1,14 +1,14 @@ # Environment variables -uv accepts the following command-line arguments as environment variables: +uv respects the following environment variables: -- `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_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 + 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 - URL as the default index when searching for packages. (Deprecated: use `UV_DEFAULT_INDEX` - instead.) + 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 use this space-separated list of URLs as additional indexes when searching for packages. (Deprecated: use `UV_INDEX` instead.) @@ -23,16 +23,17 @@ uv accepts the following command-line arguments as environment variables: - `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 - 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. + 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 this Python interpreter for all operations. -- `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_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 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 @@ -42,15 +43,14 @@ uv accepts the following command-line arguments as environment variables: 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 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 as constraints for any source distribution builds. Uses space-separated list of - files. +- `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 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 a link mode. -- `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_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. 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 @@ -79,78 +79,115 @@ uv accepts the following command-line arguments as environment variables: set, uv will use this username for publishing. - `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 the environment. - `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 updating the `uv.lock` file. - -In each case, the corresponding command-line argument takes precedence over an environment variable. - -In addition, uv respects the following environment variables: - +- `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 perform at any given time. - `UV_CONCURRENT_BUILDS`: Sets the maximum number of source distributions that uv will build concurrently at any given time. -- `UV_CONCURRENT_INSTALLS`: Used to control the number of threads used when installing and unzipping +- `UV_CONCURRENT_INSTALLS`: Controls the number of threads used when installing and unzipping packages. -- `UV_TOOL_DIR`: Used to specify the directory where uv will store managed tools. -- `UV_TOOL_BIN_DIR`: Used to specify the "bin" directory where uv will install tool executables. -- `UV_PROJECT_ENVIRONMENT`: Use to specify 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_INSTALL_DIR`: Used to specify the directory where uv will store managed Python - installations. +- `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. + 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 - [`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., + [`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 [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. -- `XDG_CONFIG_HOME`: Used to specify the path to uv user-level configuration directory on Unix - systems. -- `XDG_CACHE_HOME`: Used to specify the directory where uv stores cache files on Unix systems. -- `XDG_DATA_HOME`: Used to specify the directory where uv stores managed Python installations and - managed tools on Unix systems. -- `XDG_BIN_HOME`: Used to specify the directory where executables are installed into. -- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's - trust store. -- `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. -- `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) - for more. -- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests. -- `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout - for HTTP reads (default: 30 s). -- `NETRC`: If set, uv will read authentication information from this file instead of `~/.netrc`. -- `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). + `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. + 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`. + 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. -- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell). - `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. -- `NU_VERSION`: Used to detect the use of NuShell. -- `FISH_VERSION`: Used to detect the use of the Fish shell. -- `BASH_VERSION`: Used to detect the use of the Bash shell. -- `ZSH_VERSION`: Used to detect the use of the Zsh shell. +- `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 - 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`: Disable colors. Takes precedence over `FORCE_COLOR`. See - [no-color.org](https://no-color.org). -- `UV_NO_PROGRESS`: Disable progress indicators like spinners and progress bars. -- `FORCE_COLOR`: Enforce colors regardless of TTY support. See - [force-color.org](https://force-color.org). + 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`). + 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. + 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 + 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) + for more.