本文档介绍了 uv 的托管 Python 安装系统，包括 uv 如何下载 Python 发行版、管理安装元数据以及设置 Python 安装以供使用。该系统支持 uv python install 从预构建的分发版自动获取和安装 Python 版本。
有关发现现有 Python 安装的信息，请参阅 Python Discovery。有关通用的 Python 管理概念，请参阅 Python Management。
uv 的 Python 安装系统由几个关键组件组成，它们协同工作以提供自动化的 Python 发行版管理。
来源：crates/uv/src/commands/python/install.rs130-513 crates/uv-python/src/downloads.rs108-434 crates/uv-python/src/managed.rs95-141
安装系统依赖于描述所有可用 Python 发行版的全面元数据数据库。
下载元数据存储在 download-metadata.json 中，并包含来自 python-build-standalone 的 Python 发行版信息。
来源：crates/uv-python/fetch-download-metadata.py1-43 crates/uv-python/build.rs23-42 crates/uv-python/src/downloads.rs507-604
系统采用延迟加载元数据的方式。
| 组件 | 目的 | 实现 |
|---|---|---|
BUILTIN_PYTHON_DOWNLOADS_JSON | 嵌入的元数据字符串 | 静态包含的最小化 JSON |
PYTHON_DOWNLOADS | 运行时缓存 | OnceCell<Cow<'static, [ManagedPythonDownload]>> |
ManagedPythonDownload::iter_all() | 元数据访问 | 延迟初始化和迭代 |
来源：crates/uv-python/src/downloads.rs507-509 crates/uv-python/src/downloads.rs570-604
安装过程通过几个阶段转换用户请求。
来源：crates/uv/src/commands/python/install.rs46-80 crates/uv-python/src/downloads.rs157-267 crates/uv-python/src/downloads.rs290-347
系统自动检测当前平台并筛选可用的下载项。
| 平台组件 | 检测方法 | 筛选逻辑 |
|---|---|---|
| 架构 | Arch::from_env() | ArchRequest::satisfied_by() |
| 操作系统 | Os::from_env() | 直接相等检查 |
| Libc | Libc::from_env() | 直接相等检查 |
| 实现 | 用户请求或默认 CPython | LenientImplementationName 匹配 |
来源：crates/uv-python/src/downloads.rs249-267 crates/uv-python/src/downloads.rs299-343
一旦确定了合适的下载项，系统便执行实际的安装。
来源：crates/uv-python/src/downloads.rs623-671 crates/uv-python/src/downloads.rs673-839 crates/uv/src/commands/python/install.rs370-408
解压后，几个配置步骤可确保 Python 安装正常工作。
| 配置步骤 | 目的 | 实现 |
|---|---|---|
ensure_externally_managed() | 阻止 pip 修改 | 创建 EXTERNALLY-MANAGED 文件 |
ensure_sysconfig_patched() | 修复路径配置 | 修补 sysconfig 数据 |
ensure_canonical_executables() | 创建标准 Python 可执行文件 | 链接/复制 python、python3 等。 |
ensure_dylib_patched() | 修复动态库路径（macOS） | 更新安装名称 |
来源：crates/uv-python/src/managed.rs501-590 crates/uv-python/src/managed.rs592-672 crates/uv-python/src/managed.rs674-738
该系统将安装的 Python 版本组织在结构化的目录层次结构中。
来源：crates/uv-python/src/managed.rs114-131 crates/uv-python/src/installation.rs220-284 crates/uv/src/commands/python/install.rs196-205
该系统使用结构化键来识别 Python 安装。
| 组件 | 格式 | 示例 |
|---|---|---|
| 实现 | cpython、pypy、graalpy | cpython |
| 版本 | major.minor.patch[prerelease] | 3.12.1 |
| 操作系统 | linux、darwin、windows | linux |
| 架构 | x86_64、aarch64 等。 | x86_64 |
| Libc | gnu、musl、none | gnu |
来源：crates/uv-python/src/installation.rs220-284 crates/uv-python/src/downloads.rs115-126
安装系统提供了多种使 Python 安装可访问的机制。
来源： crates/uv/src/commands/python/install.rs515-556 crates/uv-python/src/managed.rs381-480
系统会根据安装上下文创建不同类型的可执行链接
| 链接类型 | 创建时间 | 目标名称 |
|---|---|---|
| 特定版本 | 始终（在预览模式下） | python3.12 |
| 主版本号 | 默认安装 | python3 |
| 通用 | 默认安装 | python |
来源： crates/uv/src/commands/python/install.rs530-539 crates/uv/src/commands/python/install.rs542-556
在 Windows 上，系统会选择性地将 Python 安装注册到注册表中
来源： crates/uv/src/commands/python/install.rs402-407 crates/uv-python/src/windows_registry.rs
安装系统包含多种机制来安全地处理并发操作
| 安全机制 | 目的 | 实现 |
|---|---|---|
| 目录锁定 | 防止并发修改 | LockedFile 和 .lock 文件 |
| 原子操作 | 确保安装一致性 | 临时目录和重命名 |
| 去重 | 避免重复下载 | 基于唯一键的过滤 |
| 错误处理 | 优雅的故障恢复 | 全面的错误类型 |
来源： crates/uv-python/src/managed.rs109-112 crates/uv/src/commands/python/install.rs200 crates/uv/src/commands/python/install.rs303-306