Expose toolchain-preference as a CLI and configuration file option (#…

…4424)

Exposes the option added in #4416. Adds `--toolchain-preference` and
`tool.uv.toolchain-preference` to configure if system or managed
toolchains are preferred. Users can opt-out of managed toolchains or
system toolchains entirely as well.

crates/uv-settings/src/combine.rs

@@ -5,7 +5,7 @@ use distribution_types::IndexUrl;
 use install_wheel_rs::linker::LinkMode;
 use uv_configuration::{ConfigSettings, IndexStrategy, KeyringProviderType, TargetTriple};
 use uv_resolver::{AnnotationStyle, ExcludeNewer, PreReleaseMode, ResolutionMode};
-use uv_toolchain::PythonVersion;
+use uv_toolchain::{PythonVersion, ToolchainPreference};
 
 use crate::{FilesystemOptions, PipOptions};
 
@@ -69,6 +69,7 @@ impl_combine_or!(PythonVersion);
 impl_combine_or!(ResolutionMode);
 impl_combine_or!(String);
 impl_combine_or!(TargetTriple);
+impl_combine_or!(ToolchainPreference);
 impl_combine_or!(bool);
 
 impl<T> Combine for Option<Vec<T>> {

crates/uv-settings/src/settings.rs

@@ -11,7 +11,7 @@ use uv_configuration::{
 use uv_macros::CombineOptions;
 use uv_normalize::{ExtraName, PackageName};
 use uv_resolver::{AnnotationStyle, ExcludeNewer, PreReleaseMode, ResolutionMode};
-use uv_toolchain::PythonVersion;
+use uv_toolchain::{PythonVersion, ToolchainPreference};
 
 /// A `pyproject.toml` with an (optional) `[tool.uv]` section.
 #[allow(dead_code)]
@@ -59,6 +59,7 @@ pub struct GlobalOptions {
     pub no_cache: Option<bool>,
     pub cache_dir: Option<PathBuf>,
     pub preview: Option<bool>,
+    pub toolchain_preference: Option<ToolchainPreference>,
 }
 
 /// Settings relevant to all installer operations.

crates/uv-toolchain/Cargo.toml

@@ -28,6 +28,7 @@ uv-state = { workspace = true }
 uv-warnings = { workspace = true }
 
 anyhow = { workspace = true }
+clap = { workspace = true, optional = true }
 configparser = { workspace = true }
 fs-err = { workspace = true, features = ["tokio"] }
 itertools = { workspace = true }

crates/uv-toolchain/src/discovery.rs

@@ -51,12 +51,15 @@ pub enum ToolchainRequest {
     /// Generally these refer to uv-managed toolchain downloads.
     Key(PythonDownloadRequest),
 }
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, serde::Deserialize)]
+#[serde(deny_unknown_fields, rename_all = "kebab-case")]
+#[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum ToolchainPreference {
     /// Only use managed interpreters, never use system interpreters.
     OnlyManaged,
     /// Prefer installed managed interpreters, but use system interpreters if not found.
+    /// If neither can be found, download a managed interpreter.
     #[default]
     PreferInstalledManaged,
     /// Prefer managed interpreters, even if one needs to be downloaded, but use system interpreters if found.
@@ -1177,8 +1180,8 @@ impl ToolchainPreference {
         }
     }
 
-    /// Return a [`ToolchainPreference`] based the given settings.
-    pub fn from_settings(preview: PreviewMode) -> Self {
+    /// Return a default [`ToolchainPreference`] based on the environment and preview mode.
+    pub fn default_from(preview: PreviewMode) -> Self {
         if env::var_os("UV_TEST_PYTHON_PATH").is_some() {
             debug!("Only considering system interpreters due to `UV_TEST_PYTHON_PATH`");
             Self::OnlySystem

crates/uv/Cargo.toml

@@ -33,7 +33,7 @@ uv-normalize = { workspace = true }
 uv-requirements = { workspace = true }
 uv-resolver = { workspace = true, features = ["clap"] }
 uv-settings = { workspace = true, features = ["schemars"] }
-uv-toolchain = { workspace = true }
+uv-toolchain = { workspace = true, features = ["clap", "schemars"]}
 uv-types = { workspace = true }
 uv-virtualenv = { workspace = true }
 uv-warnings = { workspace = true }

crates/uv/src/cli.rs

@@ -14,7 +14,7 @@ use uv_configuration::{
 };
 use uv_normalize::{ExtraName, PackageName};
 use uv_resolver::{AnnotationStyle, ExcludeNewer, PreReleaseMode, ResolutionMode};
-use uv_toolchain::PythonVersion;
+use uv_toolchain::{PythonVersion, ToolchainPreference};
 
 use crate::commands::{extra_name_with_clap_error, ListFormat, VersionFormat};
 use crate::compat;
@@ -89,6 +89,10 @@ pub(crate) struct GlobalArgs {
     #[arg(global = true, long, overrides_with("offline"), hide = true)]
     pub(crate) no_offline: bool,
 
+    /// Whether to use system or uv-managed Python toolchains.
+    #[arg(global = true, long)]
+    pub(crate) toolchain_preference: Option<ToolchainPreference>,
+
     /// Whether to enable experimental, preview features.
     #[arg(global = true, long, hide = true, env = "UV_PREVIEW", value_parser = clap::builder::BoolishValueParser::new(), overrides_with("no_preview"))]
     pub(crate) preview: bool,

crates/uv/src/commands/pip/compile.rs

@@ -89,6 +89,7 @@ pub(crate) async fn pip_compile(
     link_mode: LinkMode,
     python: Option<String>,
     system: bool,
+    toolchain_preference: ToolchainPreference,
     concurrency: Concurrency,
     native_tls: bool,
     quiet: bool,
@@ -154,11 +155,10 @@ pub(crate) async fn pip_compile(
     }
 
     // Find an interpreter to use for building distributions
-    let preference = ToolchainPreference::from_settings(preview);
     let environments = EnvironmentPreference::from_system_flag(system, false);
     let interpreter = if let Some(python) = python.as_ref() {
         let request = ToolchainRequest::parse(python);
-        Toolchain::find(&request, environments, preference, &cache)
+        Toolchain::find(&request, environments, toolchain_preference, &cache)
     } else {
         // TODO(zanieb): The split here hints at a problem with the abstraction; we should be able to use
         // `Toolchain::find(...)` here.
@@ -168,7 +168,7 @@ pub(crate) async fn pip_compile(
         } else {
             ToolchainRequest::default()
         };
-        Toolchain::find_best(&request, environments, preference, &cache)
+        Toolchain::find_best(&request, environments, toolchain_preference, &cache)
     }?
     .into_interpreter();
 

crates/uv/src/commands/project/add.rs

@@ -6,7 +6,7 @@ use uv_distribution::pyproject_mut::PyProjectTomlMut;
 use uv_git::GitResolver;
 use uv_requirements::{NamedRequirementsResolver, RequirementsSource, RequirementsSpecification};
 use uv_resolver::{FlatIndex, InMemoryIndex, OptionsBuilder};
-use uv_toolchain::ToolchainRequest;
+use uv_toolchain::{ToolchainPreference, ToolchainRequest};
 use uv_types::{BuildIsolation, HashStrategy, InFlight};
 
 use uv_cache::Cache;
@@ -34,6 +34,7 @@ pub(crate) async fn add(
     branch: Option<String>,
     python: Option<String>,
     settings: ResolverInstallerSettings,
+    toolchain_preference: ToolchainPreference,
     preview: PreviewMode,
     connectivity: Connectivity,
     concurrency: Concurrency,
@@ -52,6 +53,7 @@ pub(crate) async fn add(
     let venv = project::init_environment(
         project.workspace(),
         python.as_deref().map(ToolchainRequest::parse),
+        toolchain_preference,
         connectivity,
         native_tls,
         cache,

crates/uv/src/commands/project/lock.rs

@@ -18,7 +18,7 @@ use uv_resolver::{
     ExcludeNewer, FlatIndex, InMemoryIndex, Lock, OptionsBuilder, PreReleaseMode, RequiresPython,
     ResolutionMode,
 };
-use uv_toolchain::{Interpreter, ToolchainRequest};
+use uv_toolchain::{Interpreter, ToolchainPreference, ToolchainRequest};
 use uv_types::{BuildIsolation, EmptyInstalledPackages, HashStrategy, InFlight};
 use uv_warnings::warn_user;
 
@@ -33,6 +33,7 @@ pub(crate) async fn lock(
     python: Option<String>,
     settings: ResolverSettings,
     preview: PreviewMode,
+    toolchain_preference: ToolchainPreference,
     connectivity: Connectivity,
     concurrency: Concurrency,
     native_tls: bool,
@@ -50,6 +51,7 @@ pub(crate) async fn lock(
     let interpreter = project::find_interpreter(
         &workspace,
         python.as_deref().map(ToolchainRequest::parse),
+        toolchain_preference,
         connectivity,
         native_tls,
         cache,

crates/uv/src/commands/project/mod.rs

@@ -139,6 +139,7 @@ pub(crate) fn interpreter_meets_requirements(
 pub(crate) async fn find_interpreter(
     workspace: &Workspace,
     python_request: Option<ToolchainRequest>,
+    toolchain_preference: ToolchainPreference,
     connectivity: Connectivity,
     native_tls: bool,
     cache: &Cache,
@@ -183,8 +184,8 @@ pub(crate) async fn find_interpreter(
     // Locate the Python interpreter to use in the environment
     let interpreter = Toolchain::find_or_fetch(
         python_request,
-        EnvironmentPreference::Any,
-        ToolchainPreference::from_settings(PreviewMode::Enabled),
+        EnvironmentPreference::OnlySystem,
+        toolchain_preference,
         client_builder,
         cache,
     )
@@ -215,6 +216,7 @@ pub(crate) async fn find_interpreter(
 pub(crate) async fn init_environment(
     workspace: &Workspace,
     python: Option<ToolchainRequest>,
+    toolchain_preference: ToolchainPreference,
     connectivity: Connectivity,
     native_tls: bool,
     cache: &Cache,
@@ -248,8 +250,16 @@ pub(crate) async fn init_environment(
     };
 
     // Find an interpreter to create the environment with
-    let interpreter =
-        find_interpreter(workspace, python, connectivity, native_tls, cache, printer).await?;
+    let interpreter = find_interpreter(
+        workspace,
+        python,
+        toolchain_preference,
+        connectivity,
+        native_tls,
+        cache,
+        printer,
+    )
+    .await?;
 
     let venv = workspace.venv();
     writeln!(

crates/uv/src/commands/project/remove.rs

@@ -6,7 +6,7 @@ use uv_client::Connectivity;
 use uv_configuration::{Concurrency, ExtrasSpecification, PreviewMode};
 use uv_distribution::pyproject_mut::PyProjectTomlMut;
 use uv_distribution::ProjectWorkspace;
-use uv_toolchain::ToolchainRequest;
+use uv_toolchain::{ToolchainPreference, ToolchainRequest};
 use uv_warnings::warn_user;
 
 use crate::commands::pip::operations::Modifications;
@@ -20,6 +20,7 @@ pub(crate) async fn remove(
     requirements: Vec<PackageName>,
     dev: bool,
     python: Option<String>,
+    toolchain_preference: ToolchainPreference,
     preview: PreviewMode,
     connectivity: Connectivity,
     concurrency: Concurrency,
@@ -85,6 +86,7 @@ pub(crate) async fn remove(
     let venv = project::init_environment(
         project.workspace(),
         python.as_deref().map(ToolchainRequest::parse),
+        toolchain_preference,
         connectivity,
         native_tls,
         cache,

crates/uv/src/commands/project/run.rs

@@ -35,6 +35,7 @@ pub(crate) async fn run(
     settings: ResolverInstallerSettings,
     isolated: bool,
     preview: PreviewMode,
+    toolchain_preference: ToolchainPreference,
     connectivity: Connectivity,
     concurrency: Concurrency,
     native_tls: bool,
@@ -65,6 +66,7 @@ pub(crate) async fn run(
         let venv = project::init_environment(
             project.workspace(),
             python.as_deref().map(ToolchainRequest::parse),
+            toolchain_preference,
             connectivity,
             native_tls,
             cache,
@@ -141,7 +143,7 @@ pub(crate) async fn run(
             Toolchain::find_or_fetch(
                 python.as_deref().map(ToolchainRequest::parse),
                 EnvironmentPreference::Any,
-                ToolchainPreference::from_settings(PreviewMode::Enabled),
+                toolchain_preference,
                 client_builder,
                 cache,
             )

crates/uv/src/commands/project/sync.rs

@@ -16,7 +16,7 @@ use uv_git::GitResolver;
 use uv_installer::SitePackages;
 use uv_normalize::PackageName;
 use uv_resolver::{FlatIndex, InMemoryIndex, Lock};
-use uv_toolchain::{PythonEnvironment, ToolchainRequest};
+use uv_toolchain::{PythonEnvironment, ToolchainPreference, ToolchainRequest};
 use uv_types::{BuildIsolation, HashStrategy, InFlight};
 use uv_warnings::warn_user;
 
@@ -33,6 +33,7 @@ pub(crate) async fn sync(
     dev: bool,
     modifications: Modifications,
     python: Option<String>,
+    toolchain_preference: ToolchainPreference,
     settings: InstallerSettings,
     preview: PreviewMode,
     connectivity: Connectivity,
@@ -52,6 +53,7 @@ pub(crate) async fn sync(
     let venv = project::init_environment(
         project.workspace(),
         python.as_deref().map(ToolchainRequest::parse),
+        toolchain_preference,
         connectivity,
         native_tls,
         cache,

crates/uv/src/commands/tool/run.rs

@@ -30,6 +30,7 @@ pub(crate) async fn run(
     settings: ResolverInstallerSettings,
     _isolated: bool,
     preview: PreviewMode,
+    toolchain_preference: ToolchainPreference,
     connectivity: Connectivity,
     concurrency: Concurrency,
     native_tls: bool,
@@ -73,7 +74,7 @@ pub(crate) async fn run(
             .map(ToolchainRequest::parse)
             .unwrap_or_default(),
         EnvironmentPreference::OnlySystem,
-        ToolchainPreference::from_settings(preview),
+        toolchain_preference,
         cache,
     )?
     .into_interpreter();

crates/uv/src/commands/toolchain/find.rs

@@ -14,6 +14,7 @@ use crate::printer::Printer;
 #[allow(clippy::too_many_arguments)]
 pub(crate) async fn find(
     request: Option<String>,
+    toolchain_preference: ToolchainPreference,
     preview: PreviewMode,
     cache: &Cache,
     printer: Printer,
@@ -29,7 +30,7 @@ pub(crate) async fn find(
     let toolchain = Toolchain::find(
         &request,
         EnvironmentPreference::OnlySystem,
-        ToolchainPreference::from_settings(PreviewMode::Enabled),
+        toolchain_preference,
         cache,
     )?;
 

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

@@ -30,6 +30,7 @@ pub(crate) async fn list(
     kinds: ToolchainListKinds,
     all_versions: bool,
     all_platforms: bool,
+    toolchain_preference: ToolchainPreference,
     preview: PreviewMode,
     cache: &Cache,
     printer: Printer,
@@ -56,7 +57,7 @@ pub(crate) async fn list(
     let installed = find_toolchains(
         &ToolchainRequest::Any,
         EnvironmentPreference::OnlySystem,
-        ToolchainPreference::from_settings(preview),
+        toolchain_preference,
         cache,
     )
     // Raise discovery errors if critical

crates/uv/src/commands/venv.rs

@@ -42,6 +42,7 @@ use crate::shell::Shell;
 pub(crate) async fn venv(
     path: &Path,
     python_request: Option<&str>,
+    toolchain_preference: ToolchainPreference,
     link_mode: LinkMode,
     index_locations: &IndexLocations,
     index_strategy: IndexStrategy,
@@ -69,6 +70,7 @@ pub(crate) async fn venv(
         connectivity,
         seed,
         preview,
+        toolchain_preference,
         allow_existing,
         exclude_newer,
         native_tls,
@@ -118,6 +120,7 @@ async fn venv_impl(
     connectivity: Connectivity,
     seed: bool,
     preview: PreviewMode,
+    toolchain_preference: ToolchainPreference,
     allow_existing: bool,
     exclude_newer: Option<ExcludeNewer>,
     native_tls: bool,
@@ -137,7 +140,7 @@ async fn venv_impl(
     let interpreter = Toolchain::find_or_fetch(
         interpreter_request,
         EnvironmentPreference::OnlySystem,
-        ToolchainPreference::from_settings(preview),
+        toolchain_preference,
         client_builder,
         cache,
     )