Require opt-in to use alternative Python implementations

crates/uv-python/src/discovery.rs

@@ -934,21 +934,44 @@ pub(crate) fn find_python_installation(
  return result;
  };
 
- // If it's a pre-release, and pre-releases aren't allowed skip it but store it for later
+ // Check if we need to skip the interpreter because it is "not allowed", e.g., if it is a
+ // pre-release version or an alternative implementation, using it requires opt-in.
+
+ // If the interpreter has a default executable name, e.g. `python`, and was found on the
+ // search path, we consider this opt-in to use it.
+ let has_default_executable_name = installation.interpreter.has_default_executable_name()
+ && installation.source == PythonSource::SearchPath;
+
+ // If it's a pre-release and pre-releases aren't allowed, skip it — but store it for later
+ // since we'll use a pre-release if no other versions are available.
  if installation.python_version().pre().is_some()
  && !request.allows_prereleases()
  && !installation.source.allows_prereleases()
+ && !has_default_executable_name
  {
  debug!("Skipping pre-release {}", installation.key());
  first_prerelease = Some(installation.clone());
  continue;
  }
 
+ // If it's an alternative implementation and alternative implementations aren't allowed,
+ // skip it. Note we avoid querying these interpreters at all if they're on the search path
+ // and are not requested, but other sources such as the managed installations will include
+ // them.
+ if installation.is_alternative_implementation()
+ && !request.allows_alternative_implementations()
+ && !installation.source.allows_alternative_implementations()
+ && !has_default_executable_name
+ {
+ debug!("Skipping alternative implementation {}", installation.key());
+ continue;
+ }
+
  // If we didn't skip it, this is the installation to use
  return result;
  }
 
- // If we only found pre-releases, they're implicitly allowed and we should return the first one
+ // If we only found pre-releases, they're implicitly allowed and we should return the first one.
  if let Some(installation) = first_prerelease {
  return Ok(Ok(installation));
  }
@@ -1205,10 +1228,7 @@ impl PythonRequest {
  for implementation in
  ImplementationName::long_names().chain(ImplementationName::short_names())
  {
- if let Some(remainder) = value
- .to_ascii_lowercase()
- .strip_prefix(Into::<&str>::into(implementation))
- {
+ if let Some(remainder) = value.to_ascii_lowercase().strip_prefix(implementation) {
  // e.g. `pypy`
  if remainder.is_empty() {
  return Self::Implementation(
@@ -1369,6 +1389,7 @@ impl PythonRequest {
  }
  }
 
+ /// Whether this request opts-in to a pre-release Python version.
  pub(crate) fn allows_prereleases(&self) -> bool {
  match self {
  Self::Default => false,
@@ -1381,6 +1402,19 @@ impl PythonRequest {
  }
  }
 
+ /// Whether this request opts-in to an alternative Python implementation, e.g., PyPy.
+ pub(crate) fn allows_alternative_implementations(&self) -> bool {
+ match self {
+ Self::Default => false,
+ Self::Any => true,
+ Self::Version(_) => false,
+ Self::Directory(_) | Self::File(_) | Self::ExecutableName(_) => true,
+ Self::Implementation(_) => true,
+ Self::ImplementationVersion(_, _) => true,
+ Self::Key(request) => request.allows_alternative_implementations(),
+ }
+ }
+
  pub(crate) fn is_explicit_system(&self) -> bool {
  matches!(self, Self::File(_) | Self::Directory(_))
  }
@@ -1410,7 +1444,7 @@ impl PythonSource {
  matches!(self, Self::Managed)
  }
 
- /// Whether a pre-release Python installation from the source should be used without opt-in.
+ /// Whether a pre-release Python installation from this source can be used without opt-in.
  pub(crate) fn allows_prereleases(self) -> bool {
  match self {
  Self::Managed | Self::Registry | Self::MicrosoftStore => false,
@@ -1422,6 +1456,18 @@ impl PythonSource {
  | Self::DiscoveredEnvironment => true,
  }
  }
+
+ /// Whether an alternative Python implementation from this source can be used without opt-in.
+ pub(crate) fn allows_alternative_implementations(self) -> bool {
+ match self {
+ Self::Managed | Self::Registry | Self::SearchPath | Self::MicrosoftStore => false,
+ Self::CondaPrefix
+ | Self::ProvidedPath
+ | Self::ParentInterpreter
+ | Self::ActiveEnvironment
+ | Self::DiscoveredEnvironment => true,
+ }
+ }
 }
 
 impl PythonPreference {

crates/uv-python/src/downloads.rs

@@ -281,6 +281,7 @@ impl PythonDownloadRequest {
  self.satisfied_by_key(download.key())
  }
 
+ /// Whether this download request opts-in to pre-release Python versions.
  pub fn allows_prereleases(&self) -> bool {
  self.prereleases.unwrap_or_else(|| {
  self.version
@@ -289,6 +290,11 @@ impl PythonDownloadRequest {
  })
  }
 
+ /// Whether this download request opts-in to alternative Python implementations.
+ pub fn allows_alternative_implementations(&self) -> bool {
+ self.implementation.is_some()
+ }
+
  pub fn satisfied_by_interpreter(&self, interpreter: &Interpreter) -> bool {
  if let Some(version) = self.version() {
  if !version.matches_interpreter(interpreter) {

crates/uv-python/src/implementation.rs

@@ -52,18 +52,24 @@ impl LenientImplementationName {
 }
 
 impl From<&ImplementationName> for &'static str {
- fn from(v: &ImplementationName) -> &'static str {
- match v {
+ fn from(value: &ImplementationName) -> &'static str {
+ match value {
  ImplementationName::CPython => "cpython",
  ImplementationName::PyPy => "pypy",
  ImplementationName::GraalPy => "graalpy",
  }
  }
 }
 
+impl From<ImplementationName> for &'static str {
+ fn from(value: ImplementationName) -> &'static str {
+ (&value).into()
+ }
+}
+
 impl<'a> From<&'a LenientImplementationName> for &'a str {
- fn from(v: &'a LenientImplementationName) -> &'a str {
- match v {
+ fn from(value: &'a LenientImplementationName) -> &'a str {
+ match value {
  LenientImplementationName::Known(implementation) => implementation.into(),
  LenientImplementationName::Unknown(name) => name,
  }

crates/uv-python/src/installation.rs

@@ -16,7 +16,8 @@ use crate::implementation::LenientImplementationName;
 use crate::managed::{ManagedPythonInstallation, ManagedPythonInstallations};
 use crate::platform::{Arch, Libc, Os};
 use crate::{
- downloads, Error, Interpreter, PythonDownloads, PythonPreference, PythonSource, PythonVersion,
+ downloads, Error, ImplementationName, Interpreter, PythonDownloads, PythonPreference,
+ PythonSource, PythonVersion,
 };
 
 /// A Python interpreter and accompanying tools.
@@ -176,6 +177,16 @@ impl PythonInstallation {
  LenientImplementationName::from(self.interpreter.implementation_name())
  }
 
+ /// Whether this is a CPython installation.
+ ///
+ /// Returns false if it is an alternative implementation, e.g., PyPy.
+ pub(crate) fn is_alternative_implementation(&self) -> bool {
+ !matches!(
+ self.implementation(),
+ LenientImplementationName::Known(ImplementationName::CPython)
+ )
+ }
+
  /// Return the [`Arch`] of the Python installation as reported by its interpreter.
  pub fn arch(&self) -> Arch {
  self.interpreter.arch()

crates/uv-python/src/interpreter.rs

@@ -25,7 +25,9 @@ use uv_fs::{write_atomic_sync, PythonExt, Simplified};
 use crate::implementation::LenientImplementationName;
 use crate::platform::{Arch, Libc, Os};
 use crate::pointer_size::PointerSize;
-use crate::{Prefix, PythonInstallationKey, PythonVersion, Target, VirtualEnvironment};
+use crate::{
+ Prefix, PythonInstallationKey, PythonVersion, Target, VersionRequest, VirtualEnvironment,
+};
 
 /// A Python executable and its associated platform markers.
 #[derive(Debug, Clone)]
@@ -494,6 +496,21 @@ impl Interpreter {
  (version.major(), version.minor()) == self.python_tuple()
  }
  }
+
+ /// Whether or not this Python interpreter is from a default Python executable name, like
+ /// `python`, `python3`, or `python.exe`.
+ pub(crate) fn has_default_executable_name(&self) -> bool {
+ let Some(file_name) = self.sys_executable().file_name() else {
+ return false;
+ };
+ let Some(name) = file_name.to_str() else {
+ return false;
+ };
+ VersionRequest::Default
+ .executable_names(None)
+ .into_iter()
+ .any(|default_name| name == default_name.to_string())
+ }
 }
 
 /// The `EXTERNALLY-MANAGED` file in a Python installation.

crates/uv-python/src/lib.rs

@@ -1793,7 +1793,7 @@ mod tests {
  })?;
  assert!(
  matches!(result, Err(PythonNotFound { .. })),
- "We should not the pypy interpreter if not named `python` or requested; got {result:?}"
+ "We should not find the pypy interpreter if not named `python` or requested; got {result:?}"
  );
 
  // But we should find it