Validate that discovered interpreters meet the Python preference

Author: zanieb

crates/uv-python/src/discovery.rs

@@ -594,6 +594,9 @@ fn python_interpreters<'a>(
     )
     .filter(move |result| result_satisfies_environment_preference(result, environments))
     .filter(move |result| result_satisfies_version_request(result, version))
+    // Ensure that interpreters, e.g., from the search path, meet the preference for managed
+    // interpreters since the user can link them to arbitrary locations.
+    .filter(move |result| result_satisfies_python_preference(result, preference))
 }
 
 /// Lazily convert Python executables into interpreters.
@@ -696,6 +699,101 @@ fn result_satisfies_environment_preference(
     })
 }
 
+/// Returns true if a Python interpreter matches the [`PythonPreference`].
+pub fn satisfies_python_preference(
+    source: PythonSource,
+    interpreter: &Interpreter,
+    preference: PythonPreference,
+) -> bool {
+    // If the source is "explicit", we will not apply the Python preference, e.g., if the user has
+    // activated a virtual environment, we should always respect allow it. We may want to invalidate
+    // the environment in some cases, like in projects, but we can't distinguish between explicit
+    // requests for a different Python preference or a persistent preference in a configuration file
+    // which would result in overly aggressive invalidation.
+    let is_explicit = match source {
+        PythonSource::ProvidedPath
+        | PythonSource::ParentInterpreter
+        | PythonSource::ActiveEnvironment
+        | PythonSource::CondaPrefix => true,
+        PythonSource::Managed
+        | PythonSource::DiscoveredEnvironment
+        | PythonSource::SearchPath
+        | PythonSource::Registry
+        | PythonSource::MicrosoftStore
+        | PythonSource::BaseCondaPrefix => false,
+    };
+
+    match preference {
+        PythonPreference::OnlyManaged => {
+            // Perform a fast check using the source before querying the interpreter
+            if matches!(source, PythonSource::Managed) || interpreter.is_managed() {
+                true
+            } else {
+                if is_explicit {
+                    debug!(
+                        "Allowing unmanaged Python interpreter at `{}` (in conflict with the `python-preference`) since it is from source: {source}",
+                        interpreter.sys_executable().display()
+                    );
+                    true
+                } else {
+                    debug!(
+                        "Ignoring Python interpreter at `{}`: only managed interpreters allowed",
+                        interpreter.sys_executable().display()
+                    );
+                    false
+                }
+            }
+        }
+        // If not "only" a kind, any interpreter is okay
+        PythonPreference::Managed | PythonPreference::System => true,
+        PythonPreference::OnlySystem => {
+            let is_system = match source {
+                // A managed interpreter is never a system interpreter
+                PythonSource::Managed => false,
+                // We can't be sure if this is a system interpreter without checking
+                PythonSource::ProvidedPath
+                | PythonSource::ParentInterpreter
+                | PythonSource::ActiveEnvironment
+                | PythonSource::CondaPrefix
+                | PythonSource::DiscoveredEnvironment
+                | PythonSource::SearchPath
+                | PythonSource::Registry
+                | PythonSource::BaseCondaPrefix => !interpreter.is_managed(),
+                // Managed interpreters should never be found in the store
+                PythonSource::MicrosoftStore => true,
+            };
+
+            if is_system {
+                true
+            } else {
+                if is_explicit {
+                    debug!(
+                        "Allowing managed Python interpreter at `{}` (in conflict with the `python-preference`) since it is from source: {source}",
+                        interpreter.sys_executable().display()
+                    );
+                    true
+                } else {
+                    debug!(
+                        "Ignoring Python interpreter at `{}`: only system interpreters allowed",
+                        interpreter.sys_executable().display()
+                    );
+                    false
+                }
+            }
+        }
+    }
+}
+
+/// Utility for applying [`satisfies_python_preference`] to a result type.
+fn result_satisfies_python_preference(
+    result: &Result<(PythonSource, Interpreter), Error>,
+    preference: PythonPreference,
+) -> bool {
+    result.as_ref().ok().map_or(true, |(source, interpreter)| {
+        satisfies_python_preference(*source, interpreter, preference)
+    })
+}
+
 /// Check if an encountered error is critical and should stop discovery.
 ///
 /// Returns false when an error could be due to a faulty Python installation and we should continue searching for a working one.
@@ -2295,6 +2393,18 @@ impl PythonPreference {
             }
         }
     }
+
+    /// Return the canonical name.
+    // TODO(zanieb): This should be a `Display` impl and we should have a different view for
+    // the sources
+    pub fn canonical_name(&self) -> &'static str {
+        match self {
+            Self::OnlyManaged => "only managed",
+            Self::Managed => "prefer managed",
+            Self::System => "prefer system",
+            Self::OnlySystem => "only system",
+        }
+    }
 }
 
 impl fmt::Display for PythonPreference {

crates/uv-python/src/environment.rs

@@ -145,8 +145,7 @@ impl PythonEnvironment {
         let installation = match find_python_installation(
             request,
             preference,
-            // Ignore managed installations when looking for environments
-            PythonPreference::OnlySystem,
+            PythonPreference::default(),
             cache,
         )? {
             Ok(installation) => installation,

crates/uv-python/src/interpreter.rs

@@ -23,6 +23,7 @@ use uv_platform_tags::{Tags, TagsError};
 use uv_pypi_types::{ResolverMarkerEnvironment, Scheme};
 
 use crate::implementation::LenientImplementationName;
+use crate::managed::ManagedPythonInstallations;
 use crate::platform::{Arch, Libc, Os};
 use crate::pointer_size::PointerSize;
 use crate::{
@@ -225,6 +226,21 @@ impl Interpreter {
         self.prefix.is_some()
     }
 
+    /// Returns `true` if this interpreter is managed by uv.
+    ///
+    /// Returns `false` if we cannot determine the path of the uv managed Python interpreters.
+    pub fn is_managed(&self) -> bool {
+        let Ok(installations) = ManagedPythonInstallations::from_settings() else {
+            return false;
+        };
+
+        installations
+            .find_all()
+            .into_iter()
+            .flatten()
+            .any(|install| install.path() == self.sys_base_prefix)
+    }
+
     /// Returns `Some` if the environment is externally managed, optionally including an error
     /// message from the `EXTERNALLY-MANAGED` file.
     ///

crates/uv-python/src/lib.rs

@@ -5,8 +5,9 @@ use thiserror::Error;
 use uv_static::EnvVars;
 
 pub use crate::discovery::{
-    find_python_installations, EnvironmentPreference, Error as DiscoveryError, PythonDownloads,
-    PythonNotFound, PythonPreference, PythonRequest, PythonSource, PythonVariant, VersionRequest,
+    find_python_installations, satisfies_python_preference, EnvironmentPreference,
+    Error as DiscoveryError, PythonDownloads, PythonNotFound, PythonPreference, PythonRequest,
+    PythonSource, PythonVariant, VersionRequest,
 };
 pub use crate::environment::{InvalidEnvironment, InvalidEnvironmentKind, PythonEnvironment};
 pub use crate::implementation::ImplementationName;

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

@@ -3,7 +3,7 @@ use std::path::{Path, PathBuf};
 
 use itertools::Itertools;
 use owo_colors::OwoColorize;
-use tracing::debug;
+use tracing::{debug, trace};
 
 use uv_cache::Cache;
 use uv_client::{BaseClientBuilder, Connectivity, FlatIndexClient, RegistryClientBuilder};
@@ -24,9 +24,9 @@ use uv_pep440::{Version, VersionSpecifiers};
 use uv_pep508::MarkerTreeContents;
 use uv_pypi_types::Requirement;
 use uv_python::{
-    EnvironmentPreference, Interpreter, InvalidEnvironmentKind, PythonDownloads, PythonEnvironment,
-    PythonInstallation, PythonPreference, PythonRequest, PythonVariant, PythonVersionFile,
-    VersionFileDiscoveryOptions, VersionRequest,
+    satisfies_python_preference, EnvironmentPreference, Interpreter, InvalidEnvironmentKind,
+    PythonDownloads, PythonEnvironment, PythonInstallation, PythonPreference, PythonRequest,
+    PythonSource, PythonVariant, PythonVersionFile, VersionFileDiscoveryOptions, VersionRequest,
 };
 use uv_requirements::upgrade::{read_lock_requirements, LockedRequirements};
 use uv_requirements::{NamedRequirementsResolver, RequirementsSpecification};
@@ -522,6 +522,55 @@ impl ScriptPython {
     }
 }
 
+fn environment_satisfies_requirements(
+    environment: &PythonEnvironment,
+    python_request: Option<&PythonRequest>,
+    python_preference: PythonPreference,
+    requires_python: Option<&RequiresPython>,
+    cache: &Cache,
+) -> bool {
+    if let Some(request) = python_request {
+        if request.satisfied(environment.interpreter(), cache) {
+            debug!("The virtual environment's Python version satisfies `{request}`");
+        } else {
+            debug!("The virtual environment's Python version does not satisfy `{request}`");
+            return false;
+        }
+    };
+
+    if let Some(requires_python) = requires_python.as_ref() {
+        if requires_python.contains(environment.interpreter().python_version()) {
+            trace!(
+                "The virtual environment's Python version meets the project's Python requirement: `{requires_python}`"
+            );
+        } else {
+            debug!(
+                "The virtual environment's Python version does not meet the project's Python requirement: `{requires_python}`"
+            );
+            return false;
+        }
+    }
+
+    if satisfies_python_preference(
+        PythonSource::DiscoveredEnvironment,
+        environment.interpreter(),
+        python_preference,
+    ) {
+        trace!(
+            "The virtual environment's interpreter satisfies the `python-preference`: {}",
+            python_preference.canonical_name()
+        );
+    } else {
+        debug!(
+            "The virtual environment's interpreter does not satisfy the `python-preference`: {}",
+            python_preference.canonical_name()
+        );
+        return false;
+    }
+
+    true
+}
+
 impl ProjectInterpreter {
     /// Discover the interpreter to use in the current [`Workspace`].
     pub(crate) async fn discover(
@@ -549,31 +598,14 @@ impl ProjectInterpreter {
         let venv = workspace.venv();
         match PythonEnvironment::from_root(&venv, cache) {
             Ok(venv) => {
-                if python_request.as_ref().map_or(true, |request| {
-                    if request.satisfied(venv.interpreter(), cache) {
-                        debug!(
-                            "The virtual environment's Python version satisfies `{}`",
-                            request.to_canonical_string()
-                        );
-                        true
-                    } else {
-                        debug!(
-                            "The virtual environment's Python version does not satisfy `{}`",
-                            request.to_canonical_string()
-                        );
-                        false
-                    }
-                }) {
-                    if let Some(requires_python) = requires_python.as_ref() {
-                        if requires_python.contains(venv.interpreter().python_version()) {
-                            return Ok(Self::Environment(venv));
-                        }
-                        debug!(
-                            "The virtual environment's Python version does not meet the project's Python requirement: `{requires_python}`"
-                        );
-                    } else {
-                        return Ok(Self::Environment(venv));
-                    }
+                if environment_satisfies_requirements(
+                    &venv,
+                    python_request.as_ref(),
+                    python_preference,
+                    requires_python.as_ref(),
+                    cache,
+                ) {
+                    return Ok(Self::Environment(venv));
                 }
             }
             Err(uv_python::Error::MissingEnvironment(_)) => {}