uv_python_interpreter/

interpreter.rs

use std::borrow::Cow;
use std::env::consts::ARCH;
use std::fmt::{Display, Formatter};
use std::path::{Path, PathBuf};
use std::process::{Command, ExitStatus};
use std::sync::OnceLock;
use std::{env, io};

use configparser::ini::Ini;
use fs_err as fs;
use owo_colors::OwoColorize;
use same_file::is_same_file;
use serde::{Deserialize, Serialize};
use thiserror::Error;
use tracing::{debug, trace, warn};

use uv_cache::{Cache, CacheBucket, CacheEntry, CachedByTimestamp, Freshness};
use uv_cache_info::Timestamp;
use uv_cache_key::cache_digest;
use uv_fs::{
    LockedFile, LockedFileError, LockedFileMode, PythonExt, Simplified, write_atomic_sync,
};
use uv_install_wheel::Layout;
use uv_pep440::Version;
use uv_pep508::{MarkerEnvironment, StringVersion};
use uv_platform::{Arch, Libc, Os};
use uv_platform_tags::{Platform, Tags, TagsError, TagsOptions};
use uv_pypi_types::{ResolverMarkerEnvironment, Scheme};
use uv_static::EnvVars;

use crate::PointerSize;
use crate::PyVenvConfiguration;
use crate::VirtualEnvironment;
use crate::virtualenv::virtualenv_python_executable;
use uv_python_types::{
    ImplementationName, LenientImplementationName, Prefix, PythonDownloadRequest,
    PythonInstallationKey, PythonRequest, PythonVariant, Target, VersionRequest,
};
use which::which;

#[cfg(windows)]
use windows::Win32::Foundation::{APPMODEL_ERROR_NO_PACKAGE, ERROR_CANT_ACCESS_FILE, WIN32_ERROR};

/// A Python executable and its associated platform markers.
#[expect(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct Interpreter {
    platform: Platform,
    markers: Box<MarkerEnvironment>,
    scheme: Scheme,
    virtualenv: Scheme,
    manylinux_compatible: bool,
    sys_prefix: PathBuf,
    sys_base_prefix: PathBuf,
    sys_base_executable: Option<PathBuf>,
    sys_executable: PathBuf,
    site_packages: Vec<PathBuf>,
    stdlib: PathBuf,
    extension_suffixes: Vec<Box<str>>,
    standalone: bool,
    tags: OnceLock<Tags>,
    target: Option<Target>,
    prefix: Option<Prefix>,
    pointer_size: PointerSize,
    gil_disabled: bool,
    real_executable: PathBuf,
    debug_enabled: bool,
}

impl Interpreter {
    /// Detect the interpreter info for the given Python executable.
    pub fn query(executable: impl AsRef<Path>, cache: &Cache) -> Result<Self, Error> {
        let executable = executable.as_ref();
        let info = InterpreterInfo::query_cached(executable, cache)?;

        debug_assert!(
            info.sys_executable.is_absolute(),
            "`sys.executable` is not an absolute Python; Python installation is broken: {}",
            info.sys_executable.display()
        );

        Ok(Self {
            platform: info.platform,
            markers: Box::new(info.markers),
            scheme: info.scheme,
            virtualenv: info.virtualenv,
            manylinux_compatible: info.manylinux_compatible,
            sys_prefix: info.sys_prefix,
            pointer_size: info.pointer_size,
            gil_disabled: info.gil_disabled,
            debug_enabled: info.debug_enabled,
            sys_base_prefix: info.sys_base_prefix,
            sys_base_executable: info.sys_base_executable,
            sys_executable: info.sys_executable,
            site_packages: info.site_packages,
            stdlib: info.stdlib,
            extension_suffixes: info.extension_suffixes,
            standalone: info.standalone,
            tags: OnceLock::new(),
            target: None,
            prefix: None,
            real_executable: executable.to_path_buf(),
        })
    }

    /// Remove any cached metadata for the given Python executable.
    pub fn clear_cache(executable: impl AsRef<Path>, cache: &Cache) -> Result<(), Error> {
        let absolute = std::path::absolute(executable.as_ref())?;
        let canonical = canonicalize_executable(&absolute)?;
        let cache_entry = InterpreterInfo::cache_entry(&absolute, &canonical, cache);

        match fs::remove_file(cache_entry.path()) {
            Ok(()) => Ok(()),
            Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(()),
            Err(err) => Err(err.into()),
        }
    }

    /// Return a new [`Interpreter`] with the given virtual environment root.
    #[must_use]
    pub fn with_virtualenv(self, virtualenv: VirtualEnvironment) -> Self {
        // Match `site.getsitepackages()` for the new environment instead of retaining the
        // parent interpreter's site-packages paths.
        // Note: This is not `sys.path`, but a distinct list.
        let mut site_packages = Vec::new();
        if self.markers.os_name() == "nt" {
            site_packages.push(virtualenv.root.clone());
            site_packages.push(virtualenv.scheme.purelib.clone());
        } else {
            if virtualenv.scheme.platlib == virtualenv.scheme.purelib {
                site_packages.push(virtualenv.scheme.purelib.clone());
            } else {
                site_packages.push(virtualenv.scheme.platlib.clone());
                site_packages.push(virtualenv.scheme.purelib.clone());
            }
            // Some distributions add import paths that are not part of the installation scheme,
            // e.g., Debian's `dist-packages`. Build those paths as relative to the new environment,
            // excluding paths outside the parent's prefix (such as an existing venv's system site
            // packages).
            for path in &self.site_packages {
                if let Ok(relative) = path.strip_prefix(&self.sys_prefix) {
                    let path = virtualenv.root.join(relative);
                    if !site_packages.contains(&path) {
                        site_packages.push(path);
                    }
                }
            }
        }
        Self {
            scheme: virtualenv.scheme,
            sys_base_executable: Some(virtualenv.base_executable),
            sys_executable: virtualenv.executable,
            sys_prefix: virtualenv.root,
            target: None,
            prefix: None,
            site_packages,
            ..self
        }
    }

    /// Return a new [`Interpreter`] to install into the given `--target` directory.
    pub(crate) fn with_target(self, target: Target) -> io::Result<Self> {
        fs::create_dir_all(target.root())?;
        Ok(Self {
            target: Some(target),
            ..self
        })
    }

    /// Return a new [`Interpreter`] to install into the given `--prefix` directory.
    pub(crate) fn with_prefix(self, prefix: Prefix) -> io::Result<Self> {
        fs::create_dir_all(prefix.root().join(&self.virtualenv.purelib))?;
        Ok(Self {
            prefix: Some(prefix),
            ..self
        })
    }

    /// Return the base Python executable; that is, the Python executable that should be
    /// considered the "base" for the virtual environment. This is typically the Python executable
    /// from the [`Interpreter`]; however, if the interpreter is a virtual environment itself, then
    /// the base Python executable is the Python executable of the interpreter's base interpreter.
    ///
    /// This routine relies on `sys._base_executable`, falling back to `sys.executable` if unset.
    /// Broadly, this routine should be used when attempting to determine the "base Python
    /// executable" in a way that is consistent with the CPython standard library, such as when
    /// determining the `home` key for a virtual environment.
    pub fn to_base_python(&self) -> Result<PathBuf, io::Error> {
        let base_executable = self.sys_base_executable().unwrap_or(self.sys_executable());
        let base_python = std::path::absolute(base_executable)?;
        Ok(base_python)
    }

    /// Determine the base Python executable; that is, the Python executable that should be
    /// considered the "base" for the virtual environment. This is typically the Python executable
    /// from the [`Interpreter`]; however, if the interpreter is a virtual environment itself, then
    /// the base Python executable is the Python executable of the interpreter's base interpreter.
    ///
    /// This routine mimics the CPython `getpath.py` logic in order to make a more robust assessment
    /// of the appropriate base Python executable. Broadly, this routine should be used when
    /// attempting to determine the "true" base executable for a Python interpreter by resolving
    /// symlinks until a valid Python installation is found. In particular, we tend to use this
    /// routine for our own managed (or standalone) Python installations.
    pub fn find_base_python(&self) -> Result<PathBuf, io::Error> {
        let base_executable = self.sys_base_executable().unwrap_or(self.sys_executable());
        // In `python-build-standalone`, a symlinked interpreter will return its own executable path
        // as `sys._base_executable`. Using the symlinked path as the base Python executable can be
        // incorrect, since it could cause `home` to point to something that is _not_ a Python
        // installation. Specifically, if the interpreter _itself_ is symlinked to an arbitrary
        // location, we need to fully resolve it to the actual Python executable; however, if the
        // entire standalone interpreter is symlinked, then we can use the symlinked path.
        //
        // We emulate CPython's `getpath.py` to ensure that the base executable results in a valid
        // Python prefix when converted into the `home` key for `pyvenv.cfg`.
        let base_python = match find_base_python(
            base_executable,
            self.python_major(),
            self.python_minor(),
            self.variant().executable_suffix(),
        ) {
            Ok(path) => path,
            Err(err) => {
                warn!("Failed to find base Python executable: {err}");
                canonicalize_executable(base_executable)?
            }
        };
        Ok(base_python)
    }

    /// Returns the path to the Python virtual environment.
    #[inline]
    pub fn platform(&self) -> &Platform {
        &self.platform
    }

    /// Returns the [`MarkerEnvironment`] for this Python executable.
    #[inline]
    pub const fn markers(&self) -> &MarkerEnvironment {
        &self.markers
    }

    /// Return the [`ResolverMarkerEnvironment`] for this Python executable.
    pub fn to_resolver_marker_environment(&self) -> ResolverMarkerEnvironment {
        ResolverMarkerEnvironment::from(self.markers().clone())
    }

    /// Returns the [`PythonInstallationKey`] for this interpreter.
    pub fn key(&self) -> PythonInstallationKey {
        PythonInstallationKey::new(
            LenientImplementationName::from(self.implementation_name()),
            self.python_major(),
            self.python_minor(),
            self.python_patch(),
            self.python_version().pre(),
            uv_platform::Platform::new(self.os(), self.arch(), self.libc()),
            self.variant(),
        )
    }

    pub fn variant(&self) -> PythonVariant {
        if self.gil_disabled() {
            if self.debug_enabled() {
                PythonVariant::FreethreadedDebug
            } else {
                PythonVariant::Freethreaded
            }
        } else if self.debug_enabled() {
            PythonVariant::Debug
        } else {
            PythonVariant::default()
        }
    }

    /// Return the [`Arch`] reported by the interpreter platform tags.
    pub fn arch(&self) -> Arch {
        Arch::from(&self.platform().arch())
    }

    /// Return the [`Libc`] reported by the interpreter platform tags.
    pub fn libc(&self) -> Libc {
        Libc::from(self.platform().os())
    }

    /// Return the [`Os`] reported by the interpreter platform tags.
    pub fn os(&self) -> Os {
        Os::from(self.platform().os())
    }

    /// Returns the [`Tags`] for this Python executable.
    pub fn tags(&self) -> Result<&Tags, TagsError> {
        if self.tags.get().is_none() {
            let tags = Tags::from_env(
                self.platform().clone(),
                self.python_tuple(),
                self.implementation_name(),
                self.implementation_tuple(),
                TagsOptions {
                    manylinux_compatible: self.manylinux_compatible,
                    gil_disabled: self.gil_disabled,
                    debug_enabled: self.debug_enabled,
                    is_cross: false,
                },
            )?;
            self.tags.set(tags).expect("tags should not be set");
        }
        Ok(self.tags.get().expect("tags should be set"))
    }

    /// Returns `true` if the environment is a PEP 405-compliant virtual environment.
    ///
    /// See: <https://github.com/pypa/pip/blob/0ad4c94be74cc24874c6feb5bb3c2152c398a18e/src/pip/_internal/utils/virtualenv.py#L14>
    pub fn is_virtualenv(&self) -> bool {
        // Maybe this should return `false` if it's a target?
        self.sys_prefix != self.sys_base_prefix
    }

    /// Returns `true` if the environment is a `--target` environment.
    fn is_target(&self) -> bool {
        self.target.is_some()
    }

    /// Returns `true` if the environment is a `--prefix` environment.
    fn is_prefix(&self) -> bool {
        self.prefix.is_some()
    }

    /// Returns `Some` if the environment is externally managed, optionally including an error
    /// message from the `EXTERNALLY-MANAGED` file.
    ///
    /// See: <https://packaging.python.org/en/latest/specifications/externally-managed-environments/>
    pub fn is_externally_managed(&self) -> Option<ExternallyManaged> {
        // Per the spec, a virtual environment is never externally managed.
        if self.is_virtualenv() {
            return None;
        }

        // If we're installing into a target or prefix directory, it's never externally managed.
        if self.is_target() || self.is_prefix() {
            return None;
        }

        let Ok(contents) = fs::read_to_string(self.stdlib.join("EXTERNALLY-MANAGED")) else {
            return None;
        };

        let mut ini = Ini::new_cs();
        ini.set_multiline(true);

        let Ok(mut sections) = ini.read(contents) else {
            // If a file exists but is not a valid INI file, we assume the environment is
            // externally managed.
            return Some(ExternallyManaged::default());
        };

        let Some(section) = sections.get_mut("externally-managed") else {
            // If the file exists but does not contain an "externally-managed" section, we assume
            // the environment is externally managed.
            return Some(ExternallyManaged::default());
        };

        let Some(error) = section.remove("Error") else {
            // If the file exists but does not contain an "Error" key, we assume the environment is
            // externally managed.
            return Some(ExternallyManaged::default());
        };

        Some(ExternallyManaged { error })
    }

    /// Returns the `python_full_version` marker corresponding to this Python version.
    #[inline]
    pub fn python_full_version(&self) -> &StringVersion {
        self.markers.python_full_version()
    }

    /// Returns the full Python version.
    #[inline]
    pub fn python_version(&self) -> &Version {
        &self.markers.python_full_version().version
    }

    /// Returns the Python version up to the minor component.
    #[inline]
    pub fn python_minor_version(&self) -> Version {
        Version::new(self.python_version().release().iter().take(2).copied())
    }

    /// Returns the Python version up to the patch component.
    #[inline]
    pub(crate) fn python_patch_version(&self) -> Version {
        Version::new(self.python_version().release().iter().take(3).copied())
    }

    /// Return the major version component of this Python version.
    pub fn python_major(&self) -> u8 {
        let major = self.markers.python_full_version().version.release()[0];
        u8::try_from(major).expect("invalid major version")
    }

    /// Return the minor version component of this Python version.
    pub fn python_minor(&self) -> u8 {
        let minor = self.markers.python_full_version().version.release()[1];
        u8::try_from(minor).expect("invalid minor version")
    }

    /// Return the patch version component of this Python version.
    fn python_patch(&self) -> u8 {
        let minor = self.markers.python_full_version().version.release()[2];
        u8::try_from(minor).expect("invalid patch version")
    }

    /// Returns the Python version as a simple tuple, e.g., `(3, 12)`.
    pub fn python_tuple(&self) -> (u8, u8) {
        (self.python_major(), self.python_minor())
    }

    /// Return the major version of the implementation (e.g., `CPython` or `PyPy`).
    fn implementation_major(&self) -> u8 {
        let major = self.markers.implementation_version().version.release()[0];
        u8::try_from(major).expect("invalid major version")
    }

    /// Return the minor version of the implementation (e.g., `CPython` or `PyPy`).
    fn implementation_minor(&self) -> u8 {
        let minor = self.markers.implementation_version().version.release()[1];
        u8::try_from(minor).expect("invalid minor version")
    }

    /// Returns the implementation version as a simple tuple.
    pub fn implementation_tuple(&self) -> (u8, u8) {
        (self.implementation_major(), self.implementation_minor())
    }

    /// Returns the implementation name (e.g., `CPython` or `PyPy`).
    pub fn implementation_name(&self) -> &str {
        self.markers.implementation_name()
    }

    /// Return the `sys.base_prefix` path for this Python interpreter.
    pub fn sys_base_prefix(&self) -> &Path {
        &self.sys_base_prefix
    }

    /// Return the `sys.prefix` path for this Python interpreter.
    pub fn sys_prefix(&self) -> &Path {
        &self.sys_prefix
    }

    /// Return the `sys._base_executable` path for this Python interpreter. Some platforms do not
    /// have this attribute, so it may be `None`.
    fn sys_base_executable(&self) -> Option<&Path> {
        self.sys_base_executable.as_deref()
    }

    /// Return the `sys.executable` path for this Python interpreter.
    pub fn sys_executable(&self) -> &Path {
        &self.sys_executable
    }

    /// Return the recognized native extension module suffixes for this Python interpreter.
    pub fn extension_suffixes(&self) -> &[Box<str>] {
        &self.extension_suffixes
    }

    /// Return the "real" queried executable path for this Python interpreter.
    pub fn real_executable(&self) -> &Path {
        &self.real_executable
    }

    /// Return the `site.getsitepackages` for this Python interpreter.
    ///
    /// These are the paths Python will search for packages in at runtime. We use this for
    /// environment layering, but not for checking for installed packages. We could use these paths
    /// to check for installed packages, but it introduces a lot of complexity, so instead we use a
    /// simplified version that does not respect customized site-packages. See
    /// [`Interpreter::site_packages`].
    pub fn runtime_site_packages(&self) -> &[PathBuf] {
        &self.site_packages
    }

    /// Return the `stdlib` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    pub fn stdlib(&self) -> &Path {
        &self.stdlib
    }

    /// Return the `purelib` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    fn purelib(&self) -> &Path {
        &self.scheme.purelib
    }

    /// Return the `platlib` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    fn platlib(&self) -> &Path {
        &self.scheme.platlib
    }

    /// Return the `scripts` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    pub fn scripts(&self) -> &Path {
        &self.scheme.scripts
    }

    /// Return the `data` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    fn data(&self) -> &Path {
        &self.scheme.data
    }

    /// Return the `include` path for this Python interpreter, as returned by `sysconfig.get_paths()`.
    fn include(&self) -> &Path {
        &self.scheme.include
    }

    /// Return the [`Scheme`] for a virtual environment created by this [`Interpreter`].
    pub fn virtualenv(&self) -> &Scheme {
        &self.virtualenv
    }

    /// Return whether this interpreter is `manylinux` compatible.
    pub fn manylinux_compatible(&self) -> bool {
        self.manylinux_compatible
    }

    /// Return the [`PointerSize`] of the Python interpreter (i.e., 32- vs. 64-bit).
    pub fn pointer_size(&self) -> PointerSize {
        self.pointer_size
    }

    /// Return whether this is a Python 3.13+ freethreading Python, as specified by the sysconfig var
    /// `Py_GIL_DISABLED`.
    ///
    /// freethreading Python is incompatible with earlier native modules, re-introducing
    /// abiflags with a `t` flag. <https://peps.python.org/pep-0703/#build-configuration-changes>
    pub fn gil_disabled(&self) -> bool {
        self.gil_disabled
    }

    /// Return whether this is a debug build of Python, as specified by the sysconfig var
    /// `Py_DEBUG`.
    pub fn debug_enabled(&self) -> bool {
        self.debug_enabled
    }

    /// Return the `--target` directory for this interpreter, if any.
    fn target(&self) -> Option<&Target> {
        self.target.as_ref()
    }

    /// Return the `--prefix` directory for this interpreter, if any.
    fn prefix(&self) -> Option<&Prefix> {
        self.prefix.as_ref()
    }

    /// Returns `true` if an [`Interpreter`] may be a `python-build-standalone` interpreter.
    ///
    /// This method may return false positives, but it should not return false negatives. In other
    /// words, if this method returns `true`, the interpreter _may_ be from
    /// `python-build-standalone`; if it returns `false`, the interpreter is definitely _not_ from
    /// `python-build-standalone`.
    ///
    /// See: <https://github.com/astral-sh/python-build-standalone/issues/382>
    #[cfg(unix)]
    pub fn is_standalone(&self) -> bool {
        self.standalone
    }

    /// Return the [`Layout`] environment used to install wheels into this interpreter.
    pub fn layout(&self) -> Layout {
        Layout {
            python_version: self.python_tuple(),
            sys_executable: self.sys_executable().to_path_buf(),
            os_name: self.markers.os_name().to_string(),
            scheme: if let Some(target) = self.target.as_ref() {
                Scheme {
                    purelib: target.root().to_path_buf(),
                    platlib: target.root().to_path_buf(),
                    scripts: target.root().join("bin"),
                    data: target.root().to_path_buf(),
                    include: target.root().join("include"),
                }
            } else if let Some(prefix) = self.prefix.as_ref() {
                Scheme {
                    purelib: prefix.root().join(&self.virtualenv.purelib),
                    platlib: prefix.root().join(&self.virtualenv.platlib),
                    scripts: prefix.root().join(&self.virtualenv.scripts),
                    data: prefix.root().join(&self.virtualenv.data),
                    include: prefix.root().join(&self.virtualenv.include),
                }
            } else {
                Scheme {
                    purelib: self.purelib().to_path_buf(),
                    platlib: self.platlib().to_path_buf(),
                    scripts: self.scripts().to_path_buf(),
                    data: self.data().to_path_buf(),
                    include: if self.is_virtualenv() {
                        // If the interpreter is a venv, then the `include` directory has a different structure.
                        // See: https://github.com/pypa/pip/blob/0ad4c94be74cc24874c6feb5bb3c2152c398a18e/src/pip/_internal/locations/_sysconfig.py#L172
                        self.sys_prefix.join("include").join("site").join(format!(
                            "python{}.{}",
                            self.python_major(),
                            self.python_minor()
                        ))
                    } else {
                        self.include().to_path_buf()
                    },
                }
            },
        }
    }

    /// Returns an iterator over the `site-packages` directories inside the environment.
    ///
    /// In most cases, `purelib` and `platlib` will be the same, and so the iterator will contain
    /// a single element; however, in some distributions, they may be different.
    ///
    /// Some distributions also create symbolic links from `purelib` to `platlib`; in such cases, we
    /// still deduplicate the entries, returning a single path.
    ///
    /// Note this does not include all runtime site-packages directories if the interpreter has been
    /// customized. See [`Interpreter::runtime_site_packages`].
    pub fn site_packages(&self) -> impl Iterator<Item = Cow<'_, Path>> {
        let target = self.target().map(Target::root);

        let prefix = self
            .prefix()
            .map(|prefix| prefix.root().join(&self.virtualenv.purelib));

        let interpreter = if target.is_none() && prefix.is_none() {
            let purelib = self.purelib();
            let platlib = self.platlib();
            Some(std::iter::once(purelib).chain(
                if purelib == platlib || is_same_file(purelib, platlib).unwrap_or(false) {
                    None
                } else {
                    Some(platlib)
                },
            ))
        } else {
            None
        };

        target
            .into_iter()
            .map(Cow::Borrowed)
            .chain(prefix.into_iter().map(Cow::Owned))
            .chain(interpreter.into_iter().flatten().map(Cow::Borrowed))
    }

    /// Whether or not this Python interpreter is from a default Python executable name, like
    /// `python`, `python3`, or `python.exe`.
    pub 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())
    }

    /// Grab a file lock for the environment to prevent concurrent writes across processes.
    pub async fn lock(&self) -> Result<LockedFile, LockedFileError> {
        if let Some(target) = self.target() {
            // If we're installing into a `--target`, use a target-specific lockfile.
            LockedFile::acquire(
                target.root().join(".lock"),
                LockedFileMode::Exclusive,
                target.root().user_display(),
            )
            .await
        } else if let Some(prefix) = self.prefix() {
            // Likewise, if we're installing into a `--prefix`, use a prefix-specific lockfile.
            LockedFile::acquire(
                prefix.root().join(".lock"),
                LockedFileMode::Exclusive,
                prefix.root().user_display(),
            )
            .await
        } else if self.is_virtualenv() {
            // If the environment a virtualenv, use a virtualenv-specific lockfile.
            LockedFile::acquire(
                self.sys_prefix.join(".lock"),
                LockedFileMode::Exclusive,
                self.sys_prefix.user_display(),
            )
            .await
        } else {
            // Otherwise, use a global lockfile.
            LockedFile::acquire(
                env::temp_dir().join(format!("uv-{}.lock", cache_digest(&self.sys_executable))),
                LockedFileMode::Exclusive,
                self.sys_prefix.user_display(),
            )
            .await
        }
    }

    /// Check whether this interpreter satisfies the given variant.
    fn matches_variant(&self, variant: PythonVariant) -> bool {
        match variant {
            PythonVariant::Default => {
                // TODO(zanieb): Right now, we allow debug interpreters to be selected by default for
                // backwards compatibility, but we may want to change this in the future.
                if (self.python_major(), self.python_minor()) >= (3, 14) {
                    // For Python 3.14+, the free-threaded build is not considered experimental
                    // and can satisfy the default variant without opt-in
                    true
                } else {
                    // In Python 3.13 and earlier, the free-threaded build is considered
                    // experimental and requires explicit opt-in
                    !self.gil_disabled()
                }
            }
            PythonVariant::Debug => self.debug_enabled(),
            PythonVariant::Freethreaded => self.gil_disabled(),
            PythonVariant::FreethreadedDebug => self.gil_disabled() && self.debug_enabled(),
            PythonVariant::Gil => !self.gil_disabled(),
            PythonVariant::GilDebug => !self.gil_disabled() && self.debug_enabled(),
        }
    }

    /// Check whether this interpreter satisfies the given implementation.
    pub fn matches_implementation(&self, implementation: ImplementationName) -> bool {
        match implementation {
            ImplementationName::Pyodide => self.os().is_emscripten(),
            _ => self
                .implementation_name()
                .eq_ignore_ascii_case(implementation.long_name()),
        }
    }

    /// Check whether this interpreter satisfies the given request.
    pub fn matches_version_request(&self, request: &VersionRequest) -> bool {
        match request {
            VersionRequest::Any => true,
            // Do not use free-threaded interpreters by default
            VersionRequest::Default => self.matches_variant(PythonVariant::Default),
            VersionRequest::Major(major, variant) => {
                self.python_major() == *major && self.matches_variant(*variant)
            }
            VersionRequest::MajorMinor(major, minor, variant) => {
                (self.python_major(), self.python_minor()) == (*major, *minor)
                    && self.matches_variant(*variant)
            }
            VersionRequest::MajorMinorPatch(major, minor, patch, variant) => {
                (
                    self.python_major(),
                    self.python_minor(),
                    self.python_patch(),
                ) == (*major, *minor, *patch)
                    // When a patch version is included, we treat it as a request for a stable
                    // release
                    && self.python_version().pre().is_none()
                    && self.matches_variant(*variant)
            }
            VersionRequest::Range(specifiers, variant) => {
                // If the specifier contains pre-releases, use the full version for comparison.
                // Otherwise, strip pre-release so that, e.g., `>=3.14` matches `3.14.0rc3`.
                let version = if specifiers
                    .iter()
                    .any(uv_pep440::VersionSpecifier::any_prerelease)
                {
                    Cow::Borrowed(self.python_version())
                } else {
                    Cow::Owned(self.python_version().only_release())
                };
                specifiers.contains(&version) && self.matches_variant(*variant)
            }
            VersionRequest::MajorMinorPrerelease(major, minor, prerelease, variant) => {
                let version = self.python_version();
                let Some(interpreter_prerelease) = version.pre() else {
                    return false;
                };
                (
                    self.python_major(),
                    self.python_minor(),
                    interpreter_prerelease,
                ) == (*major, *minor, *prerelease)
                    && self.matches_variant(*variant)
            }
            VersionRequest::MajorMinorPatchPrerelease(major, minor, patch, prerelease, variant) => {
                let version = self.python_version();
                let Some(interpreter_prerelease) = version.pre() else {
                    return false;
                };
                (
                    self.python_major(),
                    self.python_minor(),
                    self.python_patch(),
                    interpreter_prerelease,
                ) == (*major, *minor, *patch, *prerelease)
                    && self.matches_variant(*variant)
            }
        }
    }

    /// Check whether this interpreter satisfies the given request.
    pub fn matches_download_request(&self, request: &PythonDownloadRequest) -> bool {
        let executable = self.sys_executable().display();
        if let Some(version) = request.version()
            && !self.matches_version_request(version)
        {
            let interpreter_version = self.python_version();
            debug!(
                "Skipping interpreter at `{executable}`: version `{interpreter_version}` does not match request `{version}`"
            );
            return false;
        }
        let platform = request.platform();
        let interpreter_platform = uv_platform::Platform::from(self.platform());
        if !platform.matches(&interpreter_platform) {
            debug!(
                "Skipping interpreter at `{executable}`: platform `{interpreter_platform}` does not match request `{platform}`",
            );
            return false;
        }
        if let Some(implementation) = request.implementation()
            && !self.matches_implementation(*implementation)
        {
            debug!(
                "Skipping interpreter at `{executable}`: implementation `{}` does not match request `{implementation}`",
                self.implementation_name(),
            );
            return false;
        }
        true
    }

    /// Check whether this interpreter satisfies the given request.
    pub fn matches_request(&self, request: &PythonRequest, cache: &Cache) -> bool {
        /// Returns `true` if the two paths refer to the same interpreter executable.
        fn is_same_executable(path1: &Path, path2: &Path) -> bool {
            path1 == path2 || is_same_file(path1, path2).unwrap_or(false)
        }

        match request {
            PythonRequest::Default | PythonRequest::Any => true,
            PythonRequest::Version(version_request) => {
                self.matches_version_request(version_request)
            }
            PythonRequest::Directory(directory) => {
                // `sys.prefix` points to the environment root or `sys.executable` is the same
                is_same_executable(directory, self.sys_prefix())
                    || is_same_executable(
                        virtualenv_python_executable(directory).as_path(),
                        self.sys_executable(),
                    )
            }
            PythonRequest::File(file) => {
                // The interpreter satisfies the request both if it is the venv...
                if is_same_executable(self.sys_executable(), file) {
                    return true;
                }
                // ...or if it is the base interpreter the venv was created from.
                if self
                    .sys_base_executable()
                    .is_some_and(|sys_base_executable| {
                        is_same_executable(sys_base_executable, file)
                    })
                {
                    return true;
                }
                // ...or, on Windows, if both interpreters have the same base executable. On
                // Windows, interpreters are copied rather than symlinked, so a virtual environment
                // created from within a virtual environment will _not_ evaluate to the same
                // `sys.executable`, but will have the same `sys._base_executable`.
                if cfg!(windows) {
                    if let Ok(file_interpreter) = Self::query(file, cache) {
                        if let (Some(file_base), Some(interpreter_base)) = (
                            file_interpreter.sys_base_executable(),
                            self.sys_base_executable(),
                        ) {
                            if is_same_executable(file_base, interpreter_base) {
                                return true;
                            }
                        }
                    }
                }
                false
            }
            PythonRequest::ExecutableName(name) => {
                // First, see if we have a match in the venv ...
                if self
                    .sys_executable()
                    .file_name()
                    .is_some_and(|filename| filename == name.as_str())
                {
                    return true;
                }
                // ... or the venv's base interpreter (without performing IO), if that fails, ...
                if self
                    .sys_base_executable()
                    .and_then(|executable| executable.file_name())
                    .is_some_and(|file_name| file_name == name.as_str())
                {
                    return true;
                }
                // ... check in `PATH`. The name we find here does not need to be the
                // name we install, so we can find `foopython` here which got installed as `python`.
                if which(name)
                    .ok()
                    .as_ref()
                    .and_then(|executable| executable.file_name())
                    .is_some_and(|file_name| file_name == name.as_str())
                {
                    return true;
                }
                false
            }
            PythonRequest::Implementation(implementation) => {
                self.matches_implementation(*implementation)
            }
            PythonRequest::ImplementationVersion(implementation, version) => {
                self.matches_version_request(version)
                    && self.matches_implementation(*implementation)
            }
            PythonRequest::Key(request) => self.matches_download_request(request),
        }
    }
}

/// Calls `fs_err::canonicalize` on Unix. On Windows, avoids attempting to resolve symlinks
/// but will resolve junctions if they are part of a trampoline target.
pub fn canonicalize_executable(path: impl AsRef<Path>) -> std::io::Result<PathBuf> {
    let path = path.as_ref();
    debug_assert!(
        path.is_absolute(),
        "path must be absolute: {}",
        path.display()
    );

    #[cfg(windows)]
    {
        if let Ok(Some(launcher)) = uv_trampoline_builder::Launcher::try_from_path(path) {
            Ok(dunce::canonicalize(launcher.python_path)?)
        } else {
            Ok(path.to_path_buf())
        }
    }

    #[cfg(unix)]
    fs_err::canonicalize(path)
}

/// The `EXTERNALLY-MANAGED` file in a Python installation.
///
/// See: <https://packaging.python.org/en/latest/specifications/externally-managed-environments/>
#[derive(Debug, Default, Clone)]
pub struct ExternallyManaged {
    error: Option<String>,
}

impl ExternallyManaged {
    /// Return the `EXTERNALLY-MANAGED` error message, if any.
    pub fn into_error(self) -> Option<String> {
        self.error
    }
}

#[derive(Debug, Error)]
pub struct UnexpectedResponseError {
    #[source]
    err: serde_json::Error,
    stdout: String,
    stderr: String,
    pub path: PathBuf,
}

impl Display for UnexpectedResponseError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Querying Python at `{}` returned an invalid response: {}",
            self.path.display(),
            self.err
        )?;

        let mut non_empty = false;

        if !self.stdout.trim().is_empty() {
            write!(f, "\n\n{}\n{}", "[stdout]".red(), self.stdout)?;
            non_empty = true;
        }

        if !self.stderr.trim().is_empty() {
            write!(f, "\n\n{}\n{}", "[stderr]".red(), self.stderr)?;
            non_empty = true;
        }

        if non_empty {
            writeln!(f)?;
        }

        Ok(())
    }
}

#[derive(Debug, Error)]
pub struct StatusCodeError {
    code: ExitStatus,
    stdout: String,
    stderr: String,
    pub path: PathBuf,
}

impl Display for StatusCodeError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "Querying Python at `{}` failed with exit status {}",
            self.path.display(),
            self.code
        )?;

        let mut non_empty = false;

        if !self.stdout.trim().is_empty() {
            write!(f, "\n\n{}\n{}", "[stdout]".red(), self.stdout)?;
            non_empty = true;
        }

        if !self.stderr.trim().is_empty() {
            write!(f, "\n\n{}\n{}", "[stderr]".red(), self.stderr)?;
            non_empty = true;
        }

        if non_empty {
            writeln!(f)?;
        }

        Ok(())
    }
}

#[derive(Debug, Error)]
pub enum Error {
    #[error("Failed to query Python interpreter")]
    Io(#[from] io::Error),
    #[error(transparent)]
    BrokenLink(BrokenLink),
    #[error("Python interpreter not found at `{0}`")]
    NotFound(PathBuf),
    #[error("Failed to query Python interpreter at `{path}`")]
    SpawnFailed {
        path: PathBuf,
        #[source]
        err: io::Error,
    },
    #[cfg(windows)]
    #[error("Failed to query Python interpreter at `{path}`")]
    CorruptWindowsPackage {
        path: PathBuf,
        #[source]
        err: io::Error,
    },
    #[error("Failed to query Python interpreter at `{path}`")]
    PermissionDenied {
        path: PathBuf,
        #[source]
        err: io::Error,
    },
    #[error("{0}")]
    UnexpectedResponse(UnexpectedResponseError),
    #[error("{0}")]
    StatusCode(StatusCodeError),
    #[error("Can't use Python at `{path}`")]
    QueryScript {
        #[source]
        err: InterpreterInfoError,
        path: PathBuf,
    },
    #[error("Failed to write to cache")]
    Encode(#[from] rmp_serde::encode::Error),
}

impl uv_errors::Hinted for Error {
    fn hints(&self) -> uv_errors::Hints<'_> {
        match self {
            Self::BrokenLink(err) => err.hints(),
            _ => uv_errors::Hints::none(),
        }
    }
}

#[derive(Debug, Error)]
pub struct BrokenLink {
    pub path: PathBuf,
    /// Whether we have a broken symlink (Unix) or whether the shim returned that the underlying
    /// Python went away (Windows).
    pub unix: bool,
    /// Whether the interpreter path looks like a virtual environment.
    pub venv: bool,
}

impl Display for BrokenLink {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        if self.unix {
            write!(
                f,
                "Broken symlink at `{}`, was the underlying Python interpreter removed?",
                self.path.user_display()
            )
        } else {
            write!(
                f,
                "Broken Python trampoline at `{}`, was the underlying Python interpreter removed?",
                self.path.user_display()
            )
        }
    }
}

impl uv_errors::Hinted for BrokenLink {
    fn hints(&self) -> uv_errors::Hints<'_> {
        if self.venv {
            uv_errors::Hints::from(format!(
                "Consider recreating the environment (e.g., with `{}`)",
                "uv venv".green()
            ))
        } else {
            uv_errors::Hints::none()
        }
    }
}

#[derive(Debug, Deserialize, Serialize)]
#[serde(tag = "result", rename_all = "lowercase")]
enum InterpreterInfoResult {
    Error(InterpreterInfoError),
    Success(Box<InterpreterInfo>),
}

#[derive(Debug, Error, Deserialize, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum InterpreterInfoError {
    #[error("Could not detect a glibc or a musl libc (while running on Linux)")]
    LibcNotFound,
    #[error(
        "Broken Python installation, `platform.mac_ver()` returned an empty value, please reinstall Python"
    )]
    BrokenMacVer,
    #[error("Unknown operating system: `{operating_system}`")]
    UnknownOperatingSystem { operating_system: String },
    #[error("Python {python_version} is not supported. Please use Python 3.6 or newer.")]
    UnsupportedPythonVersion { python_version: String },
    #[error("Python executable does not support `-I` flag. Please use Python 3.6 or newer.")]
    UnsupportedPython,
    #[error(
        "Python installation is missing `distutils`, which is required for packaging on older Python versions. Your system may package it separately, e.g., as `python{python_major}-distutils` or `python{python_major}.{python_minor}-distutils`."
    )]
    MissingRequiredDistutils {
        python_major: usize,
        python_minor: usize,
    },
    #[error("Only Pyodide is supported for Emscripten Python")]
    EmscriptenNotPyodide,
}

#[expect(clippy::struct_excessive_bools)]
#[derive(Debug, Deserialize, Serialize, Clone)]
pub(crate) struct InterpreterInfo {
    platform: Platform,
    markers: MarkerEnvironment,
    scheme: Scheme,
    virtualenv: Scheme,
    manylinux_compatible: bool,
    sys_prefix: PathBuf,
    sys_base_exec_prefix: PathBuf,
    sys_base_prefix: PathBuf,
    sys_base_executable: Option<PathBuf>,
    sys_executable: PathBuf,
    sys_path: Vec<PathBuf>,
    site_packages: Vec<PathBuf>,
    stdlib: PathBuf,
    extension_suffixes: Vec<Box<str>>,
    standalone: bool,
    pointer_size: PointerSize,
    gil_disabled: bool,
    debug_enabled: bool,
}

impl InterpreterInfo {
    /// Build metadata for virtual environment discovery without querying Python or using the cache.
    pub(crate) fn from_virtualenv(interpreter: &Interpreter) -> Result<Self, Error> {
        // Python reports ordinary Windows paths even when the venv was created with a verbatim path.
        let scheme = Scheme {
            purelib: interpreter.scheme.purelib.simplified().to_path_buf(),
            platlib: interpreter.scheme.platlib.simplified().to_path_buf(),
            scripts: interpreter.scheme.scripts.simplified().to_path_buf(),
            // Joining the empty relative data path adds a trailing separator that sysconfig omits.
            data: interpreter.scheme.data.simplified().components().collect(),
            include: interpreter.scheme.include.simplified().to_path_buf(),
        };
        Ok(Self {
            platform: interpreter.platform.clone(),
            markers: (*interpreter.markers).clone(),
            scheme,
            virtualenv: interpreter.virtualenv.clone(),
            manylinux_compatible: interpreter.manylinux_compatible,
            sys_prefix: interpreter.sys_prefix.simplified().to_path_buf(),
            // These fields are unused by `Interpreter`, but retained in the cache format.
            sys_base_exec_prefix: PathBuf::new(),
            sys_path: Vec::new(),
            sys_base_prefix: interpreter.sys_base_prefix.clone(),
            sys_base_executable: interpreter.sys_base_executable.clone(),
            sys_executable: std::path::absolute(interpreter.sys_executable())?
                .simplified()
                .to_path_buf(),
            site_packages: interpreter
                .site_packages
                .iter()
                .map(|path| path.simplified().to_path_buf())
                .collect(),
            stdlib: interpreter.stdlib.clone(),
            extension_suffixes: interpreter.extension_suffixes.clone(),
            standalone: interpreter.standalone,
            pointer_size: interpreter.pointer_size,
            gil_disabled: interpreter.gil_disabled,
            debug_enabled: interpreter.debug_enabled,
        })
    }

    /// Cache already prepared metadata for this executable.
    pub(crate) fn cache(&self, executable: &Path, cache: &Cache) -> Result<(), Error> {
        // The lookup must use the original path, which may differ from Python's `sys.executable`.
        let absolute = std::path::absolute(executable)?;
        let canonical = canonicalize_executable(&absolute)?;
        let cache_entry = Self::cache_entry(&absolute, &canonical, cache);
        let modified = Timestamp::from_path(&canonical)?;
        self.write_cache(&cache_entry, modified)
    }

    /// Write interpreter metadata using the same format for queried and inferred interpreters.
    fn write_cache(&self, cache_entry: &CacheEntry, modified: Timestamp) -> Result<(), Error> {
        fs::create_dir_all(cache_entry.dir())?;
        write_atomic_sync(
            cache_entry.path(),
            rmp_serde::to_vec(&CachedByTimestamp {
                timestamp: modified,
                data: self,
            })?,
        )?;
        Ok(())
    }

    /// Return the resolved [`InterpreterInfo`] for the given Python executable.
    fn query(interpreter: &Path, cache: &Cache) -> Result<Self, Error> {
        let tempdir = tempfile::tempdir_in(cache.root())?;
        Self::setup_python_query_files(tempdir.path())?;

        // Sanitize the path by (1) running under isolated mode (`-I`) to ignore any site packages
        // modifications, and then (2) adding the path containing our query script to the front of
        // `sys.path` so that we can import it.
        // There are user reports that `sitecustomize.py` output breaks worker communication, but
        // we cannot use `-S` here because interpreter discovery needs the site-initialized
        // `sys.path`. We may want to fix this in the future if there are more reports. See:
        // https://github.com/astral-sh/uv/issues/11508.
        let script = format!(
            r"import sys; sys.path = [{}] + sys.path; from python.get_interpreter_info import main; main()",
            tempdir.path().escape_for_python()
        );
        let mut command = Command::new(interpreter);
        command
            .arg("-I") // Isolated mode.
            .arg("-B") // Don't write bytecode.
            .arg("-c")
            .arg(script);

        // Disable Apple's SYSTEM_VERSION_COMPAT shim so that `platform.mac_ver()` reports
        // the real macOS version instead of "10.16" for interpreters built against older SDKs
        // (e.g., conda with MACOSX_DEPLOYMENT_TARGET=10.15).
        //
        // See:
        //
        // - https://github.com/astral-sh/uv/issues/14267
        // - https://github.com/pypa/packaging/blob/f2bbd4f578644865bc5cb2534768e46563ee7f66/src/packaging/tags.py#L436
        #[cfg(target_os = "macos")]
        command.env("SYSTEM_VERSION_COMPAT", "0");

        let output = command.output().map_err(|err| {
            match err.kind() {
                io::ErrorKind::NotFound => return Error::NotFound(interpreter.to_path_buf()),
                io::ErrorKind::PermissionDenied => {
                    return Error::PermissionDenied {
                        path: interpreter.to_path_buf(),
                        err,
                    };
                }
                _ => {}
            }
            #[cfg(windows)]
            if let Some(APPMODEL_ERROR_NO_PACKAGE | ERROR_CANT_ACCESS_FILE) = err
                .raw_os_error()
                .and_then(|code| u32::try_from(code).ok())
                .map(WIN32_ERROR)
            {
                // These error codes are returned if the Python interpreter is a corrupt MSIX
                // package, which we want to differentiate from a typical spawn failure.
                return Error::CorruptWindowsPackage {
                    path: interpreter.to_path_buf(),
                    err,
                };
            }
            Error::SpawnFailed {
                path: interpreter.to_path_buf(),
                err,
            }
        })?;

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();

            // Handle uninstalled CPython interpreters on Windows.
            //
            // The IO error from the CPython trampoline is unstructured and localized, so we check
            // whether the `home` from `pyvenv.cfg` still exists, it's missing if the Python
            // interpreter was uninstalled.
            if python_home(interpreter).is_some_and(|home| !home.exists()) {
                return Err(Error::BrokenLink(BrokenLink {
                    path: interpreter.to_path_buf(),
                    unix: false,
                    venv: uv_fs::is_virtualenv_executable(interpreter),
                }));
            }

            // If the Python version is too old, we may not even be able to invoke the query script
            if stderr.contains("Unknown option: -I") {
                return Err(Error::QueryScript {
                    err: InterpreterInfoError::UnsupportedPython,
                    path: interpreter.to_path_buf(),
                });
            }

            return Err(Error::StatusCode(StatusCodeError {
                code: output.status,
                stderr,
                stdout: String::from_utf8_lossy(&output.stdout).trim().to_string(),
                path: interpreter.to_path_buf(),
            }));
        }

        let result: InterpreterInfoResult =
            serde_json::from_slice(&output.stdout).map_err(|err| {
                let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();

                // If the Python version is too old, we may not even be able to invoke the query script
                if stderr.contains("Unknown option: -I") {
                    Error::QueryScript {
                        err: InterpreterInfoError::UnsupportedPython,
                        path: interpreter.to_path_buf(),
                    }
                } else {
                    Error::UnexpectedResponse(UnexpectedResponseError {
                        err,
                        stdout: String::from_utf8_lossy(&output.stdout).trim().to_string(),
                        stderr,
                        path: interpreter.to_path_buf(),
                    })
                }
            })?;

        match result {
            InterpreterInfoResult::Error(err) => Err(Error::QueryScript {
                err,
                path: interpreter.to_path_buf(),
            }),
            InterpreterInfoResult::Success(data) => Ok(*data),
        }
    }

    /// Duplicate the directory structure we have in `../python` into a tempdir, so we can run
    /// the Python probing scripts with `python -m python.get_interpreter_info` from that tempdir.
    fn setup_python_query_files(root: &Path) -> Result<(), Error> {
        let python_dir = root.join("python");
        fs_err::create_dir(&python_dir)?;
        fs_err::write(
            python_dir.join("get_interpreter_info.py"),
            include_str!("../python/get_interpreter_info.py"),
        )?;
        fs_err::write(
            python_dir.join("__init__.py"),
            include_str!("../python/__init__.py"),
        )?;
        let packaging_dir = python_dir.join("packaging");
        fs_err::create_dir(&packaging_dir)?;
        fs_err::write(
            packaging_dir.join("__init__.py"),
            include_str!("../python/packaging/__init__.py"),
        )?;
        fs_err::write(
            packaging_dir.join("_elffile.py"),
            include_str!("../python/packaging/_elffile.py"),
        )?;
        fs_err::write(
            packaging_dir.join("_manylinux.py"),
            include_str!("../python/packaging/_manylinux.py"),
        )?;
        fs_err::write(
            packaging_dir.join("_musllinux.py"),
            include_str!("../python/packaging/_musllinux.py"),
        )?;
        Ok(())
    }

    /// Return the cache entry for an interpreter's absolute and canonical executable paths.
    fn cache_entry(absolute: &Path, canonical: &Path, cache: &Cache) -> CacheEntry {
        let python_executable = env::var_os(EnvVars::PYTHONEXECUTABLE).map(PathBuf::from);
        let pyvenv_launcher = env::var_os(EnvVars::PYVENV_LAUNCHER).map(PathBuf::from);
        // We use the absolute path for the cache entry to avoid cache collisions for relative
        // paths. But we don't want to query the executable with symbolic links resolved because
        // that can change reported values, e.g., `sys.executable`. We include the canonical
        // path in the cache entry as well, otherwise we can have cache collisions if an
        // absolute path refers to different interpreters with matching ctimes, e.g., if you
        // have a `.venv/bin/python` pointing to both Python 3.12 and Python 3.13 that were
        // modified at the same time.
        //
        // Launcher overrides can also change the reported executable and virtual environment
        // without changing either executable path.
        let file_stem = cache_digest(&(absolute, canonical, &python_executable, &pyvenv_launcher));
        cache.entry(
            CacheBucket::Interpreter,
            // Shard interpreter metadata by host architecture, operating system, and version, to
            // invalidate the cache (e.g.) on OS upgrades.
            cache_digest(&(
                ARCH,
                uv_platform::OsType::from_env()
                    .map(|os_type| os_type.to_string())
                    .unwrap_or_default(),
                uv_platform::OsRelease::from_env()
                    .map(|os_release| os_release.to_string())
                    .unwrap_or_default(),
            )),
            format!("{file_stem}.msgpack"),
        )
    }

    /// A wrapper around [`markers::query_interpreter_info`] to cache the computed markers.
    ///
    /// Running a Python script is (relatively) expensive, and the markers won't change
    /// unless the Python executable changes, so we use the executable's last modified
    /// time as a cache key.
    fn query_cached(executable: &Path, cache: &Cache) -> Result<Self, Error> {
        let absolute = std::path::absolute(executable)?;

        // Provide a better error message if the link is broken or the file does not exist. Since
        // `canonicalize_executable` does not resolve the file on Windows, we must re-use this logic
        // for the subsequent metadata read as we may not have actually resolved the path.
        let handle_io_error = |err: io::Error| -> Error {
            if err.kind() == io::ErrorKind::NotFound {
                // Check if it looks like a venv interpreter where the underlying Python
                // installation was removed.
                if absolute
                    .symlink_metadata()
                    .is_ok_and(|metadata| metadata.is_symlink())
                {
                    Error::BrokenLink(BrokenLink {
                        path: executable.to_path_buf(),
                        unix: true,
                        venv: uv_fs::is_virtualenv_executable(executable),
                    })
                } else {
                    Error::NotFound(executable.to_path_buf())
                }
            } else {
                err.into()
            }
        };

        let canonical = canonicalize_executable(&absolute).map_err(handle_io_error)?;
        let cache_entry = Self::cache_entry(&absolute, &canonical, cache);

        // We check the timestamp of the canonicalized executable to check if an underlying
        // interpreter has been modified.
        let modified = Timestamp::from_path(canonical).map_err(handle_io_error)?;

        // Read from the cache.
        if cache
            .freshness(&cache_entry, None, None)
            .is_ok_and(Freshness::is_fresh)
        {
            if let Ok(data) = fs::read(cache_entry.path()) {
                match rmp_serde::from_slice::<CachedByTimestamp<Self>>(&data) {
                    Ok(cached) => {
                        if cached.timestamp == modified {
                            trace!(
                                "Found cached interpreter info for Python {}, skipping query of: {}",
                                cached.data.markers.python_full_version(),
                                executable.user_display()
                            );
                            return Ok(cached.data);
                        }

                        trace!(
                            "Ignoring stale interpreter markers for: {}",
                            executable.user_display()
                        );
                    }
                    Err(err) => {
                        warn!(
                            "Broken interpreter cache entry at `{}`, removing: {err}",
                            cache_entry.path().user_display()
                        );
                        let _ = fs_err::remove_file(cache_entry.path());
                    }
                }
            }
        }

        // Otherwise, run the Python script.
        trace!(
            "Querying interpreter executable at `{}`",
            executable.display()
        );
        let info = Self::query(executable, cache)?;

        // If `executable` is a pyenv shim, a bash script that redirects to the activated
        // python executable at another path, we're not allowed to cache the interpreter info.
        if is_same_file(executable, &info.sys_executable).unwrap_or(false) {
            info.write_cache(&cache_entry, modified)?;
        }

        Ok(info)
    }
}

/// Find the Python executable that should be considered the "base" for a virtual environment.
///
/// Assumes that the provided executable is that of a standalone Python interpreter.
///
/// The strategy here mimics that of `getpath.py`: we search up the ancestor path to determine
/// whether a given executable will convert into a valid Python prefix; if not, we resolve the
/// symlink and try again.
///
/// This ensures that:
///
/// 1. We avoid using symlinks to arbitrary locations as the base Python executable. For example,
///    if a user symlinks a Python _executable_ to `/Users/user/foo`, we want to avoid using
///    `/Users/user` as `home`, since it's not a Python installation, and so the relevant libraries
///    and headers won't be found when it's used as the executable directory.
///    See: <https://github.com/python/cpython/blob/a03efb533a58fd13fb0cc7f4a5c02c8406a407bd/Modules/getpath.py#L367-L400>
///
/// 2. We use the "first" resolved symlink that _is_ a valid Python prefix, and thereby preserve
///    symlinks. For example, if a user symlinks a Python _installation_ to `/Users/user/foo`, such
///    that `/Users/user/foo/bin/python` is the resulting executable, we want to use `/Users/user/foo`
///    as `home`, rather than resolving to the symlink target. Concretely, this allows users to
///    symlink patch versions (like `cpython-3.12.6-macos-aarch64-none`) to minor version aliases
///    (like `cpython-3.12-macos-aarch64-none`) and preserve those aliases in the resulting virtual
///    environments.
///
/// See: <https://github.com/python/cpython/blob/a03efb533a58fd13fb0cc7f4a5c02c8406a407bd/Modules/getpath.py#L591-L594>
fn find_base_python(
    executable: &Path,
    major: u8,
    minor: u8,
    suffix: &str,
) -> Result<PathBuf, io::Error> {
    /// Returns `true` if `path` is the root directory.
    fn is_root(path: &Path) -> bool {
        let mut components = path.components();
        components.next() == Some(std::path::Component::RootDir) && components.next().is_none()
    }

    /// Determining whether `dir` is a valid Python prefix by searching for a "landmark".
    ///
    /// See: <https://github.com/python/cpython/blob/a03efb533a58fd13fb0cc7f4a5c02c8406a407bd/Modules/getpath.py#L183>
    fn is_prefix(dir: &Path, major: u8, minor: u8, suffix: &str) -> bool {
        if cfg!(windows) {
            dir.join("Lib").join("os.py").is_file()
        } else {
            dir.join("lib")
                .join(format!("python{major}.{minor}{suffix}"))
                .join("os.py")
                .is_file()
        }
    }

    let mut executable = Cow::Borrowed(executable);

    loop {
        debug!(
            "Assessing Python executable as base candidate: {}",
            executable.display()
        );

        // Determine whether this executable will produce a valid `home` for a virtual environment.
        for prefix in executable.ancestors().take_while(|path| !is_root(path)) {
            if is_prefix(prefix, major, minor, suffix) {
                return Ok(executable.into_owned());
            }
        }

        // If not, resolve the symlink.
        let resolved = fs_err::read_link(&executable)?;

        // If the symlink is relative, resolve it relative to the executable.
        let resolved = if resolved.is_relative() {
            if let Some(parent) = executable.parent() {
                parent.join(resolved)
            } else {
                return Err(io::Error::other("Symlink has no parent directory"));
            }
        } else {
            resolved
        };

        // Normalize the resolved path.
        let resolved = uv_fs::normalize_absolute_path(&resolved)?;

        executable = Cow::Owned(resolved);
    }
}

/// Parse the `home` key from `pyvenv.cfg`, if any.
fn python_home(interpreter: &Path) -> Option<PathBuf> {
    let venv_root = interpreter.parent()?.parent()?;
    let pyvenv_cfg = PyVenvConfiguration::parse(venv_root.join("pyvenv.cfg")).ok()?;
    pyvenv_cfg.home
}

#[cfg(unix)]
#[cfg(test)]
mod tests {
    use std::str::FromStr;
    use std::time::{Duration, UNIX_EPOCH};

    use anyhow::Result;
    use fs_err as fs;
    use indoc::{formatdoc, indoc};
    use serde_json::Value;
    use tempfile::tempdir;

    use uv_cache::{Cache, CacheBucket, CachedByTimestamp};
    use uv_cache_info::Timestamp;
    use uv_pep440::Version;

    use crate::Interpreter;
    use crate::interpreter::{InterpreterInfo, canonicalize_executable};

    fn mocked_interpreter_response() -> &'static str {
        indoc! {r##"
        {
            "result": "success",
            "platform": {
                "os": {
                    "name": "manylinux",
                    "major": 2,
                    "minor": 38
                },
                "arch": "x86_64"
            },
            "manylinux_compatible": false,
            "standalone": false,
            "markers": {
                "implementation_name": "cpython",
                "implementation_version": "3.12.0",
                "os_name": "posix",
                "platform_machine": "x86_64",
                "platform_python_implementation": "CPython",
                "platform_release": "6.5.0-13-generic",
                "platform_system": "Linux",
                "platform_version": "#13-Ubuntu SMP PREEMPT_DYNAMIC Fri Nov  3 12:16:05 UTC 2023",
                "python_full_version": "3.12.0",
                "python_version": "3.12",
                "sys_platform": "linux"
            },
            "sys_base_exec_prefix": "/home/ferris/.pyenv/versions/3.12.0",
            "sys_base_prefix": "/home/ferris/.pyenv/versions/3.12.0",
            "sys_prefix": "/home/ferris/projects/uv/.venv",
            "sys_executable": "{sys_executable}",
            "sys_path": [
                "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12/lib/python3.12",
                "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12/site-packages"
            ],
            "site_packages": [
                "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12/site-packages"
            ],
            "stdlib": "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12",
            "extension_suffixes": [".cpython-312-x86_64-linux-gnu.so", ".abi3.so", ".so"],
            "scheme": {
                "data": "/home/ferris/.pyenv/versions/3.12.0",
                "include": "/home/ferris/.pyenv/versions/3.12.0/include",
                "platlib": "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12/site-packages",
                "purelib": "/home/ferris/.pyenv/versions/3.12.0/lib/python3.12/site-packages",
                "scripts": "/home/ferris/.pyenv/versions/3.12.0/bin"
            },
            "virtualenv": {
                "data": "",
                "include": "include",
                "platlib": "lib/python3.12/site-packages",
                "purelib": "lib/python3.12/site-packages",
                "scripts": "bin"
            },
            "pointer_size": "64",
            "gil_disabled": true,
            "debug_enabled": false
        }
    "##}
    }

    #[tokio::test]
    async fn test_cache_invalidation() -> Result<()> {
        let mock_dir = tempdir()?;
        let mocked_interpreter = mock_dir.path().join("python");
        let query_log = mock_dir.path().join("queries");
        let json = mocked_interpreter_response().replace(
            "{sys_executable}",
            &mocked_interpreter.display().to_string(),
        );

        let cache = Cache::temp()?.init().await?;

        fs::write(
            &mocked_interpreter,
            formatdoc! {r"
        #!/bin/sh
        echo queried >> '{}'
        echo '{json}'
        ", query_log.display()},
        )?;

        fs::set_permissions(
            &mocked_interpreter,
            std::os::unix::fs::PermissionsExt::from_mode(0o770),
        )?;
        let interpreter = Interpreter::query(&mocked_interpreter, &cache)?;
        assert_eq!(
            interpreter.markers.python_version().version,
            Version::from_str("3.12")?
        );
        assert!(cache.bucket(CacheBucket::Interpreter).is_dir());
        assert_eq!(fs::read_to_string(&query_log)?, "queried\n");

        let interpreter = Interpreter::query(&mocked_interpreter, &cache)?;
        assert_eq!(
            interpreter.markers.python_version().version,
            Version::from_str("3.12")?
        );
        assert_eq!(fs::read_to_string(&query_log)?, "queried\n");

        let absolute = std::path::absolute(&mocked_interpreter)?;
        let canonical = canonicalize_executable(&absolute)?;
        let cache_entry = InterpreterInfo::cache_entry(&absolute, &canonical, &cache);
        let mut cached: CachedByTimestamp<InterpreterInfo> =
            rmp_serde::from_slice(&fs::read(cache_entry.path())?)?;
        assert_eq!(cached.timestamp, Timestamp::from_path(&canonical)?);
        assert_eq!(
            cached.data.markers.python_version().version,
            Version::from_str("3.12")?
        );

        fs::write(
            &mocked_interpreter,
            formatdoc! {r"
        #!/bin/sh
        echo queried >> '{}'
        echo '{}'
        ", query_log.display(), json.replace("3.12", "3.13")},
        )?;

        // Back-to-back writes can share a Unix `ctime`. Store a well-formed entry with a
        // different timestamp to exercise stale-cache rejection deterministically.
        let modified = Timestamp::from_path(&canonical)?;
        cached.timestamp = if modified == Timestamp::from(UNIX_EPOCH) {
            Timestamp::from(UNIX_EPOCH + Duration::from_secs(1))
        } else {
            Timestamp::from(UNIX_EPOCH)
        };
        fs::write(cache_entry.path(), rmp_serde::to_vec(&cached)?)?;
        assert_ne!(cached.timestamp, Timestamp::from_path(&canonical)?);

        let interpreter = Interpreter::query(&mocked_interpreter, &cache)?;
        assert_eq!(
            interpreter.markers.python_version().version,
            Version::from_str("3.13")?
        );
        assert_eq!(fs::read_to_string(&query_log)?, "queried\nqueried\n");

        let refreshed: CachedByTimestamp<InterpreterInfo> =
            rmp_serde::from_slice(&fs::read(cache_entry.path())?)?;
        assert_eq!(refreshed.timestamp, Timestamp::from_path(&canonical)?);
        assert_eq!(
            refreshed.data.markers.python_version().version,
            Version::from_str("3.13")?
        );

        let interpreter = Interpreter::query(&mocked_interpreter, &cache)?;
        assert_eq!(
            interpreter.markers.python_version().version,
            Version::from_str("3.13")?
        );
        assert_eq!(fs::read_to_string(&query_log)?, "queried\nqueried\n");
        Ok(())
    }

    #[tokio::test]
    async fn test_cache_eviction_with_unchanged_executable() -> Result<()> {
        let mock_dir = tempdir()?;
        let mocked_interpreter = mock_dir.path().join("python");
        let response_file = mock_dir.path().join("response.json");
        let query_count = mock_dir.path().join("queries");

        let mut response = serde_json::from_str::<Value>(mocked_interpreter_response())?;
        response["sys_executable"] = serde_json::to_value(&mocked_interpreter)?;
        fs::write(&response_file, serde_json::to_vec(&response)?)?;
        fs::write(
            &mocked_interpreter,
            formatdoc! {r#"
                #!/bin/sh
                printf '.' >> "{}"
                cat "{}"
            "#, query_count.display(), response_file.display()},
        )?;
        fs::set_permissions(
            &mocked_interpreter,
            std::os::unix::fs::PermissionsExt::from_mode(0o770),
        )?;

        let cache = Cache::temp()?.init().await?;
        let original_version = Version::from_str("3.12.0")?;
        let updated_version = Version::from_str("3.12.13")?;

        assert_eq!(
            Interpreter::query(&mocked_interpreter, &cache)?.python_version(),
            &original_version
        );

        response["markers"]["implementation_version"] = "3.12.13".into();
        response["markers"]["python_full_version"] = "3.12.13".into();
        fs::write(&response_file, serde_json::to_vec(&response)?)?;

        assert_eq!(
            Interpreter::query(&mocked_interpreter, &cache)?.python_version(),
            &original_version,
            "an unchanged executable should retain its cached interpreter metadata"
        );

        Interpreter::clear_cache(&mocked_interpreter, &cache)?;
        assert_eq!(
            fs::read_to_string(&query_count)?,
            ".",
            "clearing cached metadata should not query the interpreter"
        );
        assert_eq!(
            Interpreter::query(&mocked_interpreter, &cache)?.python_version(),
            &updated_version,
            "clearing the cache should force the next query to run the interpreter"
        );
        assert_eq!(
            Interpreter::query(&mocked_interpreter, &cache)?.python_version(),
            &updated_version,
            "the next query should persist the updated interpreter metadata"
        );
        assert_eq!(
            fs::read_to_string(&query_count)?,
            "..",
            "the updated interpreter metadata should be cached again"
        );

        Ok(())
    }
}