Add support for toggling Python bin and registry install options via env vars (#14662)

Adds environment variables for
https://github.com/astral-sh/uv/pull/14612 and
https://github.com/astral-sh/uv/pull/14614

We can't use the Clap `BoolishValueParser` here, and the reasoning is a
little hard to explain. If we used `UV_PYTHON_INSTALL_NO_BIN`, as is our
typical pattern, it'd work, but here we allow opt-in to hard errors with
`UV_PYTHON_INSTALL_BIN=1` and I don't think we should have both
`UV_PYTHON_INSTALL_BIN` and `UV_PYTHON_INSTALL_NO_BIN`.

Consequently, this pull request introduces a new `EnvironmentOptions`
abstraction which allows us to express semantics that Clap cannot —
which we probably want anyway because we have an increasing number of
environment variables we're parsing downstream, e.g., #14544 and #14369.

crates/uv-cli/src/lib.rs

@@ -4959,11 +4959,15 @@ pub struct PythonInstallArgs {
     /// This is the default behavior. If this flag is provided explicitly, uv will error if the
     /// executable cannot be installed.
     ///
+    /// This can also be set with `UV_PYTHON_INSTALL_BIN=1`.
+    ///
     /// See `UV_PYTHON_BIN_DIR` to customize the target directory.
     #[arg(long, overrides_with("no_bin"), hide = true)]
     pub bin: bool,
 
     /// Do not install a Python executable into the `bin` directory.
+    ///
+    /// This can also be set with `UV_PYTHON_INSTALL_BIN=0`.
     #[arg(long, overrides_with("bin"), conflicts_with("default"))]
     pub no_bin: bool,
 
@@ -4971,10 +4975,14 @@ pub struct PythonInstallArgs {
     ///
     /// This is the default behavior on Windows. If this flag is provided explicitly, uv will error if the
     /// registry entry cannot be created.
+    ///
+    /// This can also be set with `UV_PYTHON_INSTALL_REGISTRY=1`.
     #[arg(long, overrides_with("no_registry"), hide = true)]
     pub registry: bool,
 
     /// Do not register the Python installation in the Windows registry.
+    ///
+    /// This can also be set with `UV_PYTHON_INSTALL_REGISTRY=0`.
     #[arg(long, overrides_with("registry"))]
     pub no_registry: bool,
 

crates/uv-settings/src/lib.rs

@@ -3,6 +3,7 @@ use std::path::{Path, PathBuf};
 
 use uv_dirs::{system_config_file, user_config_dir};
 use uv_fs::Simplified;
+use uv_static::EnvVars;
 use uv_warnings::warn_user;
 
 pub use crate::combine::*;
@@ -246,4 +247,85 @@ pub enum Error {
 
     #[error("Failed to parse: `{}`. The `{}` field is not allowed in a `uv.toml` file. `{}` is only applicable in the context of a project, and should be placed in a `pyproject.toml` file instead.", _0.user_display(), _1, _1)]
     PyprojectOnlyField(PathBuf, &'static str),
+
+    #[error("Failed to parse environment variable `{name}` with invalid value `{value}`: {err}")]
+    InvalidEnvironmentVariable {
+        name: String,
+        value: String,
+        err: String,
+    },
+}
+
+/// Options loaded from environment variables.
+///
+/// This is currently a subset of all respected environment variables, most are parsed via Clap at
+/// the CLI level, however there are limited semantics in that context.
+#[derive(Debug, Clone)]
+pub struct EnvironmentOptions {
+    pub python_install_bin: Option<bool>,
+    pub python_install_registry: Option<bool>,
+}
+
+impl EnvironmentOptions {
+    /// Create a new [`EnvironmentOptions`] from environment variables.
+    pub fn new() -> Result<Self, Error> {
+        Ok(Self {
+            python_install_bin: parse_boolish_environment_variable(EnvVars::UV_PYTHON_INSTALL_BIN)?,
+            python_install_registry: parse_boolish_environment_variable(
+                EnvVars::UV_PYTHON_INSTALL_REGISTRY,
+            )?,
+        })
+    }
+}
+
+/// Parse a boolean environment variable.
+///
+/// Adapted from Clap's `BoolishValueParser` which is dual licensed under the MIT and Apache-2.0.
+fn parse_boolish_environment_variable(name: &'static str) -> Result<Option<bool>, Error> {
+    // See `clap_builder/src/util/str_to_bool.rs`
+    // We want to match Clap's accepted values
+
+    // True values are `y`, `yes`, `t`, `true`, `on`, and `1`.
+    const TRUE_LITERALS: [&str; 6] = ["y", "yes", "t", "true", "on", "1"];
+
+    // False values are `n`, `no`, `f`, `false`, `off`, and `0`.
+    const FALSE_LITERALS: [&str; 6] = ["n", "no", "f", "false", "off", "0"];
+
+    // Converts a string literal representation of truth to true or false.
+    //
+    // `false` values are `n`, `no`, `f`, `false`, `off`, and `0` (case insensitive).
+    //
+    // Any other value will be considered as `true`.
+    fn str_to_bool(val: impl AsRef<str>) -> Option<bool> {
+        let pat: &str = &val.as_ref().to_lowercase();
+        if TRUE_LITERALS.contains(&pat) {
+            Some(true)
+        } else if FALSE_LITERALS.contains(&pat) {
+            Some(false)
+        } else {
+            None
+        }
+    }
+
+    let Some(value) = std::env::var_os(name) else {
+        return Ok(None);
+    };
+
+    let Some(value) = value.to_str() else {
+        return Err(Error::InvalidEnvironmentVariable {
+            name: name.to_string(),
+            value: value.to_string_lossy().to_string(),
+            err: "expected a valid UTF-8 string".to_string(),
+        });
+    };
+
+    let Some(value) = str_to_bool(value) else {
+        return Err(Error::InvalidEnvironmentVariable {
+            name: name.to_string(),
+            value: value.to_string(),
+            err: "expected a boolish value".to_string(),
+        });
+    };
+
+    Ok(Some(value))
 }

crates/uv-static/src/env_vars.rs

@@ -269,6 +269,12 @@ impl EnvVars {
     /// Specifies the directory for storing managed Python installations.
     pub const UV_PYTHON_INSTALL_DIR: &'static str = "UV_PYTHON_INSTALL_DIR";
 
+    /// Whether to install the Python executable into the `UV_PYTHON_BIN_DIR` directory.
+    pub const UV_PYTHON_INSTALL_BIN: &'static str = "UV_PYTHON_INSTALL_BIN";
+
+    /// Whether to install the Python executable into the Windows registry.
+    pub const UV_PYTHON_INSTALL_REGISTRY: &'static str = "UV_PYTHON_INSTALL_REGISTRY";
+
     /// Managed Python installations information is hardcoded in the `uv` binary.
     ///
     /// This variable can be set to a URL pointing to JSON to use as a list for Python installations.

crates/uv/src/lib.rs

@@ -39,7 +39,7 @@ use uv_python::PythonRequest;
 use uv_requirements::RequirementsSource;
 use uv_requirements_txt::RequirementsTxtRequirement;
 use uv_scripts::{Pep723Error, Pep723Item, Pep723ItemRef, Pep723Metadata, Pep723Script};
-use uv_settings::{Combine, FilesystemOptions, Options};
+use uv_settings::{Combine, EnvironmentOptions, FilesystemOptions, Options};
 use uv_static::EnvVars;
 use uv_warnings::{warn_user, warn_user_once};
 use uv_workspace::{DiscoveryOptions, Workspace, WorkspaceCache};
@@ -304,6 +304,9 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
         .map(FilesystemOptions::from)
         .combine(filesystem);
 
+    // Load environment variables not handled by Clap
+    let environment = EnvironmentOptions::new()?;
+
     // Resolve the global settings.
     let globals = GlobalSettings::resolve(&cli.top_level.global_args, filesystem.as_ref());
 
@@ -1391,7 +1394,7 @@ async fn run(mut cli: Cli) -> Result<ExitStatus> {
             command: PythonCommand::Install(args),
         }) => {
             // Resolve the settings from the command-line arguments and workspace configuration.
-            let args = settings::PythonInstallSettings::resolve(args, filesystem);
+            let args = settings::PythonInstallSettings::resolve(args, filesystem, environment);
             show_settings!(args);
             // TODO(john): If we later want to support `--upgrade`, we need to replace this.
             let upgrade = false;

crates/uv/src/settings.rs

@@ -38,8 +38,8 @@ use uv_resolver::{
     AnnotationStyle, DependencyMode, ExcludeNewer, ForkStrategy, PrereleaseMode, ResolutionMode,
 };
 use uv_settings::{
-    Combine, FilesystemOptions, Options, PipOptions, PublishOptions, PythonInstallMirrors,
-    ResolverInstallerOptions, ResolverOptions,
+    Combine, EnvironmentOptions, FilesystemOptions, Options, PipOptions, PublishOptions,
+    PythonInstallMirrors, ResolverInstallerOptions, ResolverOptions,
 };
 use uv_static::EnvVars;
 use uv_torch::TorchMode;
@@ -944,7 +944,11 @@ pub(crate) struct PythonInstallSettings {
 impl PythonInstallSettings {
     /// Resolve the [`PythonInstallSettings`] from the CLI and filesystem configuration.
     #[allow(clippy::needless_pass_by_value)]
-    pub(crate) fn resolve(args: PythonInstallArgs, filesystem: Option<FilesystemOptions>) -> Self {
+    pub(crate) fn resolve(
+        args: PythonInstallArgs,
+        filesystem: Option<FilesystemOptions>,
+        environment: EnvironmentOptions,
+    ) -> Self {
         let options = filesystem.map(FilesystemOptions::into_options);
         let (python_mirror, pypy_mirror, python_downloads_json_url) = match options {
             Some(options) => (
@@ -979,8 +983,9 @@ impl PythonInstallSettings {
             targets,
             reinstall,
             force,
-            bin: flag(bin, no_bin, "bin"),
-            registry: flag(registry, no_registry, "registry"),
+            bin: flag(bin, no_bin, "bin").or(environment.python_install_bin),
+            registry: flag(registry, no_registry, "registry")
+                .or(environment.python_install_registry),
             python_install_mirror: python_mirror,
             pypy_install_mirror: pypy_mirror,
             python_downloads_json_url,

crates/uv/tests/it/help.rs

@@ -506,10 +506,14 @@ fn help_subsubcommand() {
               [env: UV_PYTHON_INSTALL_DIR=]
 
           --no-bin
-              Do not install a Python executable into the `bin` directory
+              Do not install a Python executable into the `bin` directory.
+              
+              This can also be set with `UV_PYTHON_INSTALL_BIN=0`.
 
           --no-registry
-              Do not register the Python installation in the Windows registry
+              Do not register the Python installation in the Windows registry.
+              
+              This can also be set with `UV_PYTHON_INSTALL_REGISTRY=0`.
 
           --mirror <MIRROR>
               Set the URL to use as the source for downloading Python installations.

crates/uv/tests/it/python_install.rs

@@ -445,6 +445,15 @@ fn python_install_preview() {
     exit_code: 1
     ----- stdout -----
 
+    ----- stderr -----
+    error: Failed to install executable for cpython-3.13.5-[PLATFORM]
+      Caused by: Executable already exists at `[BIN]/python3.13` but is not managed by uv; use `--force` to replace it
+    ");
+    uv_snapshot!(context.filters(), context.python_install().arg("--preview").arg("3.13").env(EnvVars::UV_PYTHON_INSTALL_BIN, "1"), @r"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+
     ----- stderr -----
     error: Failed to install executable for cpython-3.13.5-[PLATFORM]
       Caused by: Executable already exists at `[BIN]/python3.13` but is not managed by uv; use `--force` to replace it
@@ -456,6 +465,13 @@ fn python_install_preview() {
     exit_code: 0
     ----- stdout -----
 
+    ----- stderr -----
+    ");
+    uv_snapshot!(context.filters(), context.python_install().arg("--preview").arg("3.13").env(EnvVars::UV_PYTHON_INSTALL_BIN, "0"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
     ----- stderr -----
     ");
 
@@ -643,7 +659,7 @@ fn python_install_preview_upgrade() {
         .child(format!("python3.12{}", std::env::consts::EXE_SUFFIX));
 
     // Install 3.12.5
-    uv_snapshot!(context.filters(), context.python_install().arg("--preview").arg("3.12.5"), @r###"
+    uv_snapshot!(context.filters(), context.python_install().arg("--preview").arg("3.12.5"), @r"
     success: true
     exit_code: 0
     ----- stdout -----
@@ -651,7 +667,7 @@ fn python_install_preview_upgrade() {
     ----- stderr -----
     Installed Python 3.12.5 in [TIME]
      + cpython-3.12.5-[PLATFORM] (python3.12)
-    "###);
+    ");
 
     // Installing with a patch version should cause the link to be to the patch installation.
     if cfg!(unix) {

docs/reference/cli.md

@@ -2796,7 +2796,8 @@ uv python install [OPTIONS] [TARGETS]...
 <p>May also be set with the <code>UV_PYTHON_INSTALL_MIRROR</code> environment variable.</p></dd><dt id="uv-python-install--native-tls"><a href="#uv-python-install--native-tls"><code>--native-tls</code></a></dt><dd><p>Whether to load TLS certificates from the platform's native certificate store.</p>
 <p>By default, uv loads certificates from the bundled <code>webpki-roots</code> crate. The <code>webpki-roots</code> are a reliable set of trust roots from Mozilla, and including them in uv improves portability and performance (especially on macOS).</p>
 <p>However, in some cases, you may want to use the platform's native certificate store, especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's certificate store.</p>
-<p>May also be set with the <code>UV_NATIVE_TLS</code> environment variable.</p></dd><dt id="uv-python-install--no-bin"><a href="#uv-python-install--no-bin"><code>--no-bin</code></a></dt><dd><p>Do not install a Python executable into the <code>bin</code> directory</p>
+<p>May also be set with the <code>UV_NATIVE_TLS</code> environment variable.</p></dd><dt id="uv-python-install--no-bin"><a href="#uv-python-install--no-bin"><code>--no-bin</code></a></dt><dd><p>Do not install a Python executable into the <code>bin</code> directory.</p>
+<p>This can also be set with <code>UV_PYTHON_INSTALL_BIN=0</code>.</p>
 </dd><dt id="uv-python-install--no-cache"><a href="#uv-python-install--no-cache"><code>--no-cache</code></a>, <code>--no-cache-dir</code>, <code>-n</code></dt><dd><p>Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation</p>
 <p>May also be set with the <code>UV_NO_CACHE</code> environment variable.</p></dd><dt id="uv-python-install--no-config"><a href="#uv-python-install--no-config"><code>--no-config</code></a></dt><dd><p>Avoid discovering configuration files (<code>pyproject.toml</code>, <code>uv.toml</code>).</p>
 <p>Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.</p>
@@ -2805,7 +2806,8 @@ uv python install [OPTIONS] [TARGETS]...
 <p>May also be set with the <code>UV_NO_MANAGED_PYTHON</code> environment variable.</p></dd><dt id="uv-python-install--no-progress"><a href="#uv-python-install--no-progress"><code>--no-progress</code></a></dt><dd><p>Hide all progress outputs.</p>
 <p>For example, spinners or progress bars.</p>
 <p>May also be set with the <code>UV_NO_PROGRESS</code> environment variable.</p></dd><dt id="uv-python-install--no-python-downloads"><a href="#uv-python-install--no-python-downloads"><code>--no-python-downloads</code></a></dt><dd><p>Disable automatic downloads of Python.</p>
-</dd><dt id="uv-python-install--no-registry"><a href="#uv-python-install--no-registry"><code>--no-registry</code></a></dt><dd><p>Do not register the Python installation in the Windows registry</p>
+</dd><dt id="uv-python-install--no-registry"><a href="#uv-python-install--no-registry"><code>--no-registry</code></a></dt><dd><p>Do not register the Python installation in the Windows registry.</p>
+<p>This can also be set with <code>UV_PYTHON_INSTALL_REGISTRY=0</code>.</p>
 </dd><dt id="uv-python-install--offline"><a href="#uv-python-install--offline"><code>--offline</code></a></dt><dd><p>Disable network access.</p>
 <p>When disabled, uv will only use locally cached data and locally available files.</p>
 <p>May also be set with the <code>UV_OFFLINE</code> environment variable.</p></dd><dt id="uv-python-install--project"><a href="#uv-python-install--project"><code>--project</code></a> <i>project</i></dt><dd><p>Run the command within the given project directory.</p>

docs/reference/environment.md

@@ -376,6 +376,10 @@ This will allow for setting each property of the Python installation, mostly the
 
 Note that currently, only local paths are supported.
 
+### `UV_PYTHON_INSTALL_BIN`
+
+Whether to install the Python executable into the `UV_PYTHON_BIN_DIR` directory.
+
 ### `UV_PYTHON_INSTALL_DIR`
 
 Specifies the directory for storing managed Python installations.
@@ -390,6 +394,10 @@ The provided URL will replace `https://github.com/astral-sh/python-build-standal
 `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
 Distributions can be read from a local directory by using the `file://` URL scheme.
 
+### `UV_PYTHON_INSTALL_REGISTRY`
+
+Whether to install the Python executable into the Windows registry.
+
 ### `UV_PYTHON_PREFERENCE`
 
 Whether uv should prefer system or managed Python versions.