Python 发现

相关源文件

• crates/uv-python/Cargo.toml
• crates/uv-python/src/discovery.rs
• crates/uv-python/src/downloads.rs
• crates/uv-python/src/installation.rs
• crates/uv-python/src/lib.rs
• crates/uv-python/src/managed.rs
• crates/uv/src/commands/python/install.rs
• crates/uv/src/commands/python/list.rs
• crates/uv/src/commands/python/uninstall.rs
• crates/uv/tests/it/common/mod.rs
• crates/uv/tests/it/python_find.rs
• crates/uv/tests/it/python_install.rs
• crates/uv/tests/it/run.rs

本文档涵盖了 uv 的 Python 发现系统，该系统负责根据用户请求和配置的首选项查找和选择 Python 解释器。Python 发现是决定将使用哪个 Python 解释器来运行项目环境、工具执行和其他操作的核心机制。

有关下载和安装托管 Python 版本的信息，请参阅 Python 安装。有关项目工作区 Python 要求的详细信息，请参阅 工作区。

概述

uv 中的 Python 发现遵循可配置的搜索策略，该策略按首选项顺序考虑多个 Python 解释器来源。该系统可以从虚拟环境、托管安装、系统 PATH 和特定于平台的目录（如 Windows 注册表）中发现 Python。

Python 发现流程

来源：crates/uv-python/src/discovery.rs884-923 crates/uv-python/src/discovery.rs416-468

请求类型

发现系统通过 PythonRequest 枚举接受不同类型的 Python 请求，允许用户以多种方式指定其要求。

请求类型	示例	描述
默认	-	使用合适的默认 Python
任意	--python=any	接受任何可用的 Python
版本	--python=3.12	特定版本要求
文件	--python=/usr/bin/python3	可执行文件的直接路径
目录	--python=.venv	Python 安装目录的路径
可执行文件名	--python=python3.12	PATH 查找的可执行文件名
实现	--python=pypy	不带版本号的特定实现
实现版本	--python=pypy@3.10	带有版本的实现
键	--python=cpython-3.12-linux-x86_64	托管下载的安装密钥

来源：crates/uv-python/src/discovery.rs44-68

首选项配置

两个关键的首选项系统控制发现行为

Python 首选项

PythonPreference 枚举控制托管 Python 安装和系统 Python 安装之间的优先级

Python 首选项层级

环境首选项

EnvironmentPreference 枚举控制是否允许虚拟环境

• OnlyVirtual - 只允许虚拟环境
• ExplicitSystem - 优先使用虚拟环境，如果明确要求则允许使用系统环境
• OnlySystem - 只允许系统解释器，忽略虚拟环境
• Any - 允许任何环境类型

来源：crates/uv-python/src/discovery.rs74-89 crates/uv-python/src/discovery.rs129-140

发现来源

Python 发现根据首选项以可配置的顺序搜索多个来源

Python 发现来源

虚拟环境发现

python_executables_from_virtual_environments() 函数在虚拟环境中搜索 Python

1. 活动环境 - 检查 VIRTUAL_ENV 环境变量
2. Conda 环境 - 检查 CONDA_PREFIX 以查找 conda 环境
3. 已发现的环境 - 在父目录中搜索 .venv 目录

来源：crates/uv-python/src/discovery.rs259-292

系统 Python 发现

python_executables_from_installed() 函数根据 PythonPreference 搜索系统来源

1. 托管安装 - uv 托管的 Python 安装，来自 ManagedPythonInstallations
2. PATH 搜索 - 通过 python_executables_from_search_path() 进行标准 PATH 可执行文件搜索
3. Windows 注册表 - PEP 514 注册表条目（仅限 Windows）
4. Microsoft Store - 已知的 Microsoft Store Python 位置（仅限 Windows）

来源：crates/uv-python/src/discovery.rs312-414

PATH 搜索策略

python_executables_from_search_path() 函数实现了一个智能搜索，它会

• 按顺序搜索每个 PATH 目录
• 查找特定版本的可执行文件（例如，python3.12、python3）
• 包含特定实现的名称（例如，pypy3.10）
• 过滤 Windows Store 快捷方式
• 通过目录句柄进行去重，以避免符号链接循环

来源：crates/uv-python/src/discovery.rs482-561

解释器验证

找到的可执行文件必须通过 python_interpreters_from_executables() 函数验证为工作的 Python 解释器

解释器验证管道

验证过程

1. 查询解释器 - 运行 Python 和元数据提取脚本
2. 错误处理 - 通过 Error::is_critical() 区分关键错误和非关键错误
3. 环境过滤 - 检查解释器是否满足 EnvironmentPreference
4. 版本匹配 - 验证解释器是否与版本要求匹配

来源：crates/uv-python/src/discovery.rs671-690 crates/uv-python/src/discovery.rs799-849

集成点

版本文件集成

发现系统通过版本文件系统与版本文件（.python-version、pyproject.toml）集成

• 版本文件请求被转换为 PythonRequest::Version
• 项目 requires-python 被转换为版本约束
• 当未指定显式 Python 时，版本文件发现会影响默认请求

托管 Python 集成

发现系统与托管 Python 安装集成

• ManagedPythonInstallations::find_matching_current_platform() 提供可用的托管安装
• 托管安装在解释器查询之前按版本兼容性进行过滤
• 安装密钥可以直接用作 PythonRequest::Key

自动下载集成

当发现失败时，系统可以通过 PythonInstallation::find_or_download() 自动下载 Python

1. 尝试使用 find_python_installation() 进行正常发现
2. 失败时，检查下载是否启用以及请求是否兼容
3. 将 PythonRequest 转换为 PythonDownloadRequest
4. 通过 PythonInstallation::fetch() 下载和安装

来源：crates/uv-python/src/installation.rs78-141

错误处理

发现错误被分类以实现智能回退行为

• 关键错误 - 立即停止发现（I/O 错误、解释器启动失败）
• 非关键错误 - 继续搜索（解释器响应错误、文件丢失）
• 缺少 Python - 如果启用，可以触发自动下载

Error::is_critical() 方法决定发现是否应在错误后继续。

来源：crates/uv-python/src/discovery.rs799-849