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

@@ -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

Cargo.lock

@@ -5264,6 +5264,9 @@ dependencies = [
 [[package]]
 name = "uv-static"
 version = "0.0.1"
+dependencies = [
+ "uv-macros",
+]
 
 [[package]]
 name = "uv-tool"

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(())
 }

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,
 }

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(&current, &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::<Vec<_>>()
+            .join("\n");
+        output.push_str(&format!("- `{var}`: {doc}\n"));
+    }
+
+    output
+}
+
+#[cfg(test)]
+mod tests;

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 })
+}

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,
 }

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,
 }

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)?,
     }

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::<Vec<_>>()
+        .join("\n")
+}
+
+fn get_env_var_pattern_from_attr(attrs: &[Attribute]) -> Option<String> {
+    attrs
+        .iter()
+        .find(|attr| attr.path().is_ident("attr_env_var_pattern"))
+        .and_then(|attr| attr.parse_args::<LitStr>().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
+}

crates/uv-static/Cargo.toml

@@ -16,3 +16,4 @@ doctest = false
 workspace = true
 
 [dependencies]
+uv-macros = { workspace = true }

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.
+    /// 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.
+    /// (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.
+    /// 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.
+    /// (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: <https://hatch.pypa.io/dev/config/dependency/#local>.
+    #[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";
 }

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`
+  URL as the default index when searching for packages.
-  instead.)
+  (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
+  use the first Python interpreter found in the system `PATH`.
-  intended for use in continuous integration (CI) or containerized environments and should be used
+  WARNING: `UV_SYSTEM_PYTHON=true` is intended for use in continuous integration (CI)
-  with caution, as modifying the system Python can lead to unexpected behavior.
+  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
+- `UV_BREAK_SYSTEM_PACKAGES`: Equivalent to the `--break-system-packages` command-line argument. If set to `true`,
-  set to `true`, uv will allow the installation of packages that conflict with system-installed
+  uv will allow the installation of packages that conflict with system-installed packages.
-  packages. WARNING: `UV_BREAK_SYSTEM_PACKAGES=true` is intended for use in continuous integration
+  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
+  (CI) or containerized environments and should be used with caution, as modifying the system
-  can lead to unexpected behavior.
+  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
+- `UV_BUILD_CONSTRAINT`: Equivalent to the `--build-constraint` command-line argument. If set, uv will use this file
-  will use this file as constraints for any source distribution builds. Uses space-separated list of
+  as constraints for any source distribution builds. Uses space-separated list of files.
-  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_NO_BUILD_ISOLATION`: Equivalent to the `--no-build-isolation` command-line argument. If set, uv will
-  uv will skip isolation when building source distributions.
+  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.
-
+- `UV_PREVIEW`: Equivalent to the `--preview` argument. Enables preview mode.
-In each case, the corresponding command-line argument takes precedence over an environment variable.
+- `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.
-In addition, uv respects the following environment variables:
+- `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_DIR`: Specifies the directory where uv stores managed tools.
-- `UV_TOOL_BIN_DIR`: Used to specify the "bin" directory where uv will install tool executables.
+- `UV_TOOL_BIN_DIR`: Specifies the "bin" directory for installing tool executables.
-- `UV_PROJECT_ENVIRONMENT`: Use to specify the path to the directory to use for a project virtual
+- `UV_PROJECT_ENVIRONMENT`: Specifies the path to the directory to use for a project virtual environment.
-  environment. See the
+  See the [project documentation](../concepts/projects.md#configuring-the-project-environment-path)
-  [project documentation](../concepts/projects.md#configuring-the-project-environment-path) for more
+  for more details.
-  details.
+- `UV_PYTHON_BIN_DIR`: Specifies the directory to place links to installed, managed Python executables.
-- `UV_PYTHON_INSTALL_DIR`: Used to specify the directory where uv will store managed Python
+- `UV_PYTHON_INSTALL_DIR`: Specifies the directory for storing managed Python installations.
-  installations.
 - `UV_PYTHON_INSTALL_MIRROR`: Managed Python installations are downloaded from
-  [`python-build-standalone`](https://github.com/indygreg/python-build-standalone). This variable
+  [`python-build-standalone`](https://github.com/indygreg/python-build-standalone).
-  can be set to a mirror URL to use a different source for Python installations. The provided URL
+  This variable can be set to a mirror URL to use a different source for Python installations.
-  will replace `https://github.com/indygreg/python-build-standalone/releases/download` in, e.g.,
+  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
+  `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
-  local directory by using the `file://` URL scheme.
+  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
+- `UV_NO_WRAP`: Use to disable line wrapping for diagnostics.
-  systems.
+- `UV_STACK_SIZE`: Use to control the stack size used by uv. Typically more relevant for Windows in debug mode.
-- `XDG_CACHE_HOME`: Used to specify the directory where uv stores cache files on Unix systems.
+- `UV_INDEX_{name}_USERNAME`: Generates the environment variable key for the HTTP Basic authentication username.
-- `XDG_DATA_HOME`: Used to specify the directory where uv stores managed Python installations and
+- `UV_INDEX_{name}_PASSWORD`: Generates the environment variable key for the HTTP Basic authentication password.
-  managed tools on Unix systems.
+- `XDG_CONFIG_DIRS`: Path to system-level configuration directory on Unix systems.
-- `XDG_BIN_HOME`: Used to specify the directory where executables are installed into.
+- `SYSTEMDRIVE`: Path to system-level configuration directory on Windows systems.
-- `SSL_CERT_FILE`: If set, uv will use this file as the certificate bundle instead of the system's
+- `XDG_CONFIG_HOME`: Path to user-level configuration directory on Unix systems.
-  trust store.
+- `XDG_CACHE_HOME`: Path to cache directory on Unix systems.
-- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication. This should be a single
+- `XDG_DATA_HOME`: Path to directory for storing managed Python installations and tools.
-  file containing both the certificate and the private key in PEM format.
+- `XDG_BIN_HOME`: Path to directory where executables are installed.
-- `RUST_LOG`: If set, uv will use this value as the log level for its `--verbose` output. Accepts
+- `SSL_CERT_FILE`: Custom certificate bundle file path for SSL connections.
-  any filter compatible with the `tracing_subscriber` crate. For example, `RUST_LOG=trace` will
+- `SSL_CLIENT_CERT`: If set, uv will use this file for mTLS authentication.
-  enable trace-level logging. See the
+  This should be a single file containing both the certificate and the private key in PEM format.
-  [tracing documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax)
+- `HTTP_PROXY`: Proxy for HTTP requests.
-  for more.
+- `HTTPS_PROXY`: Proxy for HTTPS requests.
-- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`: The proxy to use for all HTTP/HTTPS requests.
+- `ALL_PROXY`: General proxy for all network requests.
-- `HTTP_TIMEOUT` (or `UV_HTTP_TIMEOUT`): If set, uv will use this value (in seconds) as the timeout
+- `UV_HTTP_TIMEOUT`: Timeout (in seconds) for HTTP requests. (default: 30 s)
-  for HTTP reads (default: 30 s).
+- `UV_REQUEST_TIMEOUT`: Timeout (in seconds) for HTTP requests. Equivalent to `UV_HTTP_TIMEOUT`.
-- `NETRC`: If set, uv will read authentication information from this file instead of `~/.netrc`.
+- `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:
+- `PYC_INVALIDATION_MODE`: The validation modes to use when run with `--compile`.
-  [`PycInvalidationMode`](https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode).
+  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.
+- `PROMPT`: Used to detect the use of the Windows Command Prompt (as opposed to PowerShell).
-- `FISH_VERSION`: Used to detect the use of the Fish shell.
+- `NU_VERSION`: Used to detect `NuShell` usage.
-- `BASH_VERSION`: Used to detect the use of the Bash shell.
+- `FISH_VERSION`: Used to detect Fish shell usage.
-- `ZSH_VERSION`: Used to detect the use of the Zsh shell.
+- `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
+  deployment target (i.e., the minimum supported macOS version).
-  least-recent non-EOL macOS version at time of writing.
+  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`: Disables colored output (takes precedence over `FORCE_COLOR`).
-  [no-color.org](https://no-color.org).
+  See [no-color.org](https://no-color.org).
-- `UV_NO_PROGRESS`: Disable progress indicators like spinners and progress bars.
+- `UV_NO_PROGRESS`: Disables all progress output. For example, spinners and progress bars.
-- `FORCE_COLOR`: Enforce colors regardless of TTY support. See
+- `FORCE_COLOR`: Forces colored output regardless of terminal support.
-  [force-color.org](https://force-color.org).
+  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.