Add support for configuring python-downloads with UV_PYTHON_DOWNLOADS

crates/uv-cli/src/lib.rs

@@ -120,11 +120,13 @@ pub struct GlobalArgs {
     )]
     pub python_preference: Option<PythonPreference>,
 
-    /// Allow automatically downloading Python when required.
+    #[allow(clippy::doc_markdown)]
+    /// Allow automatically downloading Python when required. [env: "UV_PYTHON_DOWNLOADS=auto"]
     #[arg(global = true, long, help_heading = "Python options", hide = true)]
     pub allow_python_downloads: bool,
 
-    /// Disable automatic downloads of Python.
+    #[allow(clippy::doc_markdown)]
+    /// Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
     #[arg(global = true, long, help_heading = "Python options")]
     pub no_python_downloads: bool,
 

crates/uv-dev/src/generate_cli_reference.rs

@@ -20,6 +20,11 @@ const REPLACEMENTS: &[(&str, &str)] = &[
         "<code>uv help python</code>",
         "<a href=\"#uv-python\">uv python</a>",
     ),
+    // Drop the manually included `env` section for `--no-python-downloads`
+    // TODO(zanieb): In general, we should show all of the environment variables in the reference
+    // but this one is non-standard so it's the only one included right now. When we tackle the rest
+    // we can fix the formatting.
+    (" [env: &quot;UV<em>PYTHON</em>DOWNLOADS=never&quot;]", ""),
 ];
 
 const SHOW_HIDDEN_COMMANDS: &[&str] = &["generate-shell-completion"];

crates/uv-python/src/discovery.rs

@@ -89,6 +89,19 @@ pub enum PythonDownloads {
     Never,
 }
 
+impl FromStr for PythonDownloads {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_ascii_lowercase().as_str() {
+            "auto" | "automatic" | "true" | "1" => Ok(PythonDownloads::Automatic),
+            "manual" => Ok(PythonDownloads::Manual),
+            "never" | "false" | "0" => Ok(PythonDownloads::Never),
+            _ => Err(format!("Invalid value for `python-download`: '{s}'")),
+        }
+    }
+}
+
 impl From<bool> for PythonDownloads {
     fn from(value: bool) -> Self {
         if value {

crates/uv/src/settings.rs

@@ -117,6 +117,7 @@ impl GlobalSettings {
                 .unwrap_or_else(PythonPreference::default_from_env),
             python_downloads: flag(args.allow_python_downloads, args.no_python_downloads)
                 .map(PythonDownloads::from)
+                .combine(env(env::UV_PYTHON_DOWNLOADS))
                 .combine(workspace.and_then(|workspace| workspace.globals.python_downloads))
                 .unwrap_or_default(),
             no_progress: args.no_progress,
@@ -2174,6 +2175,11 @@ mod env {
 
     pub(super) const CONCURRENT_INSTALLS: (&str, &str) =
         ("UV_CONCURRENT_INSTALLS", "a non-zero integer");
+
+    pub(super) const UV_PYTHON_DOWNLOADS: (&str, &str) = (
+        "UV_PYTHON_DOWNLOADS",
+        "one of 'auto', 'true', 'manual', 'never', or 'false'",
+    );
 }
 
 /// Attempt to load and parse an environment variable with the given name.

crates/uv/tests/help.rs

@@ -42,7 +42,7 @@ fn help() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -104,7 +104,7 @@ fn help_flag() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -165,7 +165,7 @@ fn help_short_flag() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -281,7 +281,7 @@ fn help_subcommand() {
                 installations
 
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet
@@ -430,7 +430,7 @@ fn help_subsubcommand() {
                 installations
 
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet
@@ -533,7 +533,7 @@ fn help_flag_subcommand() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -585,7 +585,7 @@ fn help_flag_subsubcommand() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -717,7 +717,7 @@ fn help_with_global_option() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output
@@ -816,7 +816,7 @@ fn help_with_no_pager() {
               Whether to prefer uv-managed or system Python installations [env: UV_PYTHON_PREFERENCE=]
               [possible values: only-managed, managed, system, only-system]
           --no-python-downloads
-              Disable automatic downloads of Python
+              Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
 
     Global options:
       -q, --quiet                      Do not print any output

docs/configuration/environment.md

@@ -58,6 +58,9 @@ uv accepts the following command-line arguments as environment variables:
   exclude distributions published after the specified date.
 - `UV_PYTHON_PREFERENCE`: Equivalent to the `--python-preference` command-line argument. Whether uv
   should prefer system or managed Python versions.
+- `UV_PYTHON_DOWNLOADS`: Equivalent to the
+  [`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the
+  `--no-python-downloads` option. Whether uv should allow Python downloads.
 
 In each case, the corresponding command-line argument takes precedence over an environment variable.