Add UV_PYTHON_DOWNLOADS_JSON_URL to set custom managed python sources

Cargo.toml

@@ -189,6 +189,7 @@ winsafe = { version = "0.0.22", features = ["kernel"] }
 wiremock = { version = "0.6.2" }
 xz2 = { version = "0.1.7" }
 zip = { version = "0.6.6", default-features = false, features = ["deflate"] }
+once_cell = { version = "1.20.2" }
 
 [workspace.metadata.cargo-shear]
 ignored = ["flate2", "xz2"]

crates/uv-python/Cargo.toml

@@ -59,6 +59,7 @@ tokio-util = { workspace = true, features = ["compat"] }
 tracing = { workspace = true }
 url = { workspace = true }
 which = { workspace = true }
+once_cell = { workspace = true }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 procfs = { workspace = true }

crates/uv-python/src/downloads.inc

@@ -3,11 +3,7 @@
 // Generated with `crates/uv-python/template-download-metadata.py`
 // From template at `crates/uv-python/src/downloads.inc.mustache`
 
-use crate::platform::ArchVariant;
-use crate::PythonVariant;
-use uv_pep440::{Prerelease, PrereleaseKind};
-
-pub(crate) const PYTHON_DOWNLOADS: &[ManagedPythonDownload] = &[
+&[
     ManagedPythonDownload {
         key: PythonInstallationKey {
             major: 3,
@@ -22400,4 +22396,4 @@ pub(crate) const PYTHON_DOWNLOADS: &[ManagedPythonDownload] = &[
         url: "https://downloads.python.org/pypy/pypy3.7-v7.3.3-win32.zip",
         sha256: Some("a282ce40aa4f853e877a5dbb38f0a586a29e563ae9ba82fd50c7e5dc465fb649")
     },
-];
+]

crates/uv-python/src/downloads.inc.mustache

@@ -1,11 +1,7 @@
 // Generated with `{{generated_with}}`
 // From template at `{{generated_from}}`
 
-use uv_pep440::{Prerelease, PrereleaseKind};
-use crate::PythonVariant;
-use crate::platform::ArchVariant;
-
-pub(crate) const PYTHON_DOWNLOADS: &[ManagedPythonDownload] = &[
+&[
     {{#versions}}
     ManagedPythonDownload {
         key: PythonInstallationKey {
@@ -36,4 +32,4 @@ pub(crate) const PYTHON_DOWNLOADS: &[ManagedPythonDownload] = &[
         {{/value.sha256}}
     },
     {{/versions}}
-];
+]

crates/uv-python/src/downloads.rs

@@ -1,3 +1,5 @@
+use std::borrow::Cow;
+use std::collections::HashMap;
 use std::fmt::Display;
 use std::io;
 use std::path::{Path, PathBuf};
@@ -7,8 +9,10 @@ use std::task::{Context, Poll};
 use std::time::{Duration, SystemTime};
 
 use futures::TryStreamExt;
+use once_cell::sync::OnceCell;
 use owo_colors::OwoColorize;
 use reqwest_retry::RetryPolicy;
+use serde::Deserialize;
 use thiserror::Error;
 use tokio::io::{AsyncRead, ReadBuf};
 use tokio_util::compat::FuturesAsyncReadCompatExt;
@@ -20,6 +24,7 @@ use uv_client::{is_extended_transient_error, WrappedReqwestError};
 use uv_distribution_filename::{ExtensionError, SourceDistExtension};
 use uv_extract::hash::Hasher;
 use uv_fs::{rename_with_retry, Simplified};
+use uv_pep440::{Prerelease, PrereleaseKind};
 use uv_pypi_types::{HashAlgorithm, HashDigest};
 use uv_static::EnvVars;
 
@@ -29,14 +34,17 @@ use crate::implementation::{
 use crate::installation::PythonInstallationKey;
 use crate::libc::LibcDetectionError;
 use crate::managed::ManagedPythonInstallation;
-use crate::platform::{self, Arch, Libc, Os};
+use crate::platform::{self, Arch, ArchVariant, Libc, Os};
+use crate::PythonVariant;
 use crate::{Interpreter, PythonRequest, PythonVersion, VersionRequest};
 
 #[derive(Error, Debug)]
 pub enum Error {
     #[error(transparent)]
     Io(#[from] io::Error),
     #[error(transparent)]
+    SerdeJson(#[from] serde_json::Error),
+    #[error(transparent)]
     ImplementationError(#[from] ImplementationError),
     #[error("Expected download URL (`{0}`) to end in a supported file extension: {1}")]
     MissingExtension(String, ExtensionError),
@@ -86,9 +94,11 @@ pub enum Error {
     Mirror(&'static str, &'static str),
     #[error(transparent)]
     LibcDetection(#[from] LibcDetectionError),
+    #[error("Remote python downloads JSON is not yet supported, please use a local path (without `file://` prefix)")]
+    RemoteJSONNotSupported(),
 }
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Clone)]
 pub struct ManagedPythonDownload {
     key: PythonInstallationKey,
     url: &'static str,
@@ -245,9 +255,11 @@ impl PythonDownloadRequest {
     }
 
     /// Iterate over all [`PythonDownload`]'s that match this request.
-    pub fn iter_downloads(&self) -> impl Iterator<Item = &'static ManagedPythonDownload> + '_ {
-        ManagedPythonDownload::iter_all()
-            .filter(move |download| self.satisfied_by_download(download))
+    pub fn iter_downloads(
+        &self,
+    ) -> Result<impl Iterator<Item = &'static ManagedPythonDownload> + use<'_>, Error> {
+        Ok(ManagedPythonDownload::iter_all()?
+            .filter(move |download| self.satisfied_by_download(download)))
     }
 
     /// Whether this request is satisfied by an installation key.
@@ -445,7 +457,30 @@ impl FromStr for PythonDownloadRequest {
     }
 }
 
-include!("downloads.inc");
+const BUILTIN_PYTHON_DOWNLOADS: &[ManagedPythonDownload] = include!("downloads.inc");
+static PYTHON_DOWNLOADS: OnceCell<std::borrow::Cow<'static, [ManagedPythonDownload]>> =
+    OnceCell::new();
+
+#[derive(Debug, Deserialize, Clone)]
+struct JsonPythonDownload {
+    name: String,
+    arch: JsonArch,
+    os: String,
+    libc: String,
+    major: u8,
+    minor: u8,
+    patch: u8,
+    prerelease: Option<String>,
+    url: String,
+    sha256: Option<String>,
+    variant: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+struct JsonArch {
+    family: String,
+    variant: Option<String>,
+}
 
 #[derive(Debug, Clone)]
 pub enum DownloadResult {
@@ -459,18 +494,141 @@ impl ManagedPythonDownload {
         request: &PythonDownloadRequest,
     ) -> Result<&'static ManagedPythonDownload, Error> {
         request
-            .iter_downloads()
+            .iter_downloads()?
             .next()
             .ok_or(Error::NoDownloadFound(request.clone()))
     }
 
     /// Iterate over all [`ManagedPythonDownload`]s.
-    pub fn iter_all() -> impl Iterator<Item = &'static ManagedPythonDownload> {
-        PYTHON_DOWNLOADS
-            .iter()
-            // TODO(konsti): musl python-build-standalone builds are currently broken (statically
-            // linked), so we pretend they don't exist. https://github.com/astral-sh/uv/issues/4242
-            .filter(|download| download.key.libc != Libc::Some(target_lexicon::Environment::Musl))
+    pub fn iter_all() -> Result<impl Iterator<Item = &'static ManagedPythonDownload>, Error> {
+        let runtime_source = std::env::var(EnvVars::UV_PYTHON_DOWNLOADS_JSON_URL);
+
+        let downloads = PYTHON_DOWNLOADS.get_or_try_init(|| {
+            if let Ok(json_source) = &runtime_source {
+                if Url::parse(json_source).is_ok() {
+                    return Err(Error::RemoteJSONNotSupported());
+                }
+
+                let file = match fs_err::File::open(json_source) {
+                    Ok(file) => file,
+                    Err(e) => { Err(Error::Io(e)) }?,
+                };
+
+                let json_downloads: HashMap<String, JsonPythonDownload> =
+                    serde_json::from_reader(file)?;
+
+                let result = json_downloads
+                    .into_iter()
+                    .filter_map(|(key, entry)| {
+                        let implementation = match entry.name.as_str() {
+                            "cpython" => {
+                                LenientImplementationName::Known(ImplementationName::CPython)
+                            }
+                            "pypy" => LenientImplementationName::Known(ImplementationName::PyPy),
+                            _ => LenientImplementationName::Unknown(entry.name.clone()),
+                        };
+
+                        let arch_str = if let Some(variant) = entry.arch.variant {
+                            format!("{}_{}", entry.arch.family, variant)
+                        } else {
+                            entry.arch.family
+                        };
+
+                        let arch = match Arch::from_str(&arch_str) {
+                            Ok(arch) => arch,
+                            Err(e) => {
+                                debug!("Skipping entry {key}: Invalid arch '{arch_str}' - {e}");
+                                return None;
+                            }
+                        };
+
+                        let os = match Os::from_str(&entry.os) {
+                            Ok(os) => os,
+                            Err(e) => {
+                                debug!("Skipping entry {}: Invalid OS '{}' - {}", key, entry.os, e);
+                                return None;
+                            }
+                        };
+
+                        let libc = match Libc::from_str(&entry.libc) {
+                            Ok(libc) => libc,
+                            Err(e) => {
+                                debug!(
+                                    "Skipping entry {}: Invalid libc '{}' - {}",
+                                    key, entry.libc, e
+                                );
+                                return None;
+                            }
+                        };
+
+                        let variant = entry
+                            .variant
+                            .as_deref()
+                            .map(PythonVariant::from_str)
+                            .transpose()
+                            .unwrap_or_else(|()| {
+                                debug!(
+                                    "Skipping entry {key}: Unknown python variant - {}",
+                                    entry.variant.unwrap_or_default()
+                                );
+                                None
+                            })
+                            .unwrap_or(PythonVariant::Default);
+
+                        let version_str = format!(
+                            "{}.{}.{}{}",
+                            entry.major,
+                            entry.minor,
+                            entry.patch,
+                            entry.prerelease.as_deref().unwrap_or_default()
+                        );
+
+                        let version = match PythonVersion::from_str(&version_str) {
+                            Ok(version) => version,
+                            Err(e) => {
+                                debug!(
+                                    "Skipping entry {key}: Invalid version '{version_str}' - {e}"
+                                );
+                                return None;
+                            }
+                        };
+
+                        let url = Box::leak(entry.url.into_boxed_str()) as &'static str;
+                        let sha256 = entry
+                            .sha256
+                            .map(|s| Box::leak(s.into_boxed_str()) as &'static str);
+
+                        Some(ManagedPythonDownload {
+                            key: PythonInstallationKey::new_from_version(
+                                implementation,
+                                &version,
+                                os,
+                                arch,
+                                libc,
+                                variant,
+                            ),
+                            url,
+                            sha256,
+                        })
+                    })
+                    .collect();
+                Ok(Cow::Owned(result))
+            } else {
+                Ok(Cow::Borrowed(BUILTIN_PYTHON_DOWNLOADS))
+            }
+        })?;
+
+        let iter = if runtime_source.is_ok() {
+            itertools::Either::Left(downloads.iter())
+        } else {
+            itertools::Either::Right(downloads.iter().filter(|download| {
+                // TODO(konsti): musl python-build-standalone builds are currently broken (statically
+                // linked), so we pretend they don't exist. https://github.com/astral-sh/uv/issues/4242
+                download.key.libc != Libc::Some(target_lexicon::Environment::Musl)
+            }))
+        };
+
+        Ok(iter)
     }
 
     pub fn url(&self) -> &'static str {

crates/uv-python/src/installation.rs

@@ -294,7 +294,7 @@ impl PythonInstallationKey {
         }
     }
 
-    fn new_from_version(
+    pub fn new_from_version(
         implementation: LenientImplementationName,
         version: &PythonVersion,
         os: Os,

crates/uv-static/src/env_vars.rs

@@ -244,6 +244,14 @@ impl EnvVars {
     /// Specifies the directory for storing managed Python installations.
     pub const UV_PYTHON_INSTALL_DIR: &'static str = "UV_PYTHON_INSTALL_DIR";
 
+    /// 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.
+    /// This will allow for setting each property of the Python installation, mostly the url part for offline mirror.
+    ///
+    /// Note that currently, only local paths are supported.
+    pub const UV_PYTHON_DOWNLOADS_JSON_URL: &'static str = "UV_PYTHON_DOWNLOADS_JSON_URL";
+
     /// Managed Python installations are downloaded from the Astral
     /// [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project.
     ///

crates/uv/src/commands/python/list.rs

@@ -93,6 +93,7 @@ pub(crate) async fn list(
         let downloads = download_request
             .as_ref()
             .map(PythonDownloadRequest::iter_downloads)
+            .transpose()?
             .into_iter()
             .flatten();
 

docs/configuration/environment.md

@@ -311,6 +311,15 @@ Equivalent to the
 [`python-downloads`](../reference/settings.md#python-downloads) setting and, when disabled, the
 `--no-python-downloads` option. Whether uv should allow Python downloads.
 
+### `UV_PYTHON_DOWNLOADS_JSON_URL`
+
+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.
+This will allow for setting each property of the Python installation, mostly the url part for offline mirror.
+
+Note that currently, only local paths are supported.
+
 ### `UV_PYTHON_INSTALL_DIR`
 
 Specifies the directory for storing managed Python installations.