uv Python 版本管理实战：安装、自动下载与多版本管理指南

本文基于 uv 仓库中的 Python 安装指南 展开，系统讲解如何使用 uv python 命令组安装和管理 Python 解释器：从最简的 uv python install 到指定版本、多版本并存、PyPy 等替代实现，再到自动按需下载、与系统 Python 共存、补丁版本升级等完整工作流。读完本文，你可以掌握 uv 托管（managed）Python 的完整生命周期管理，并理解其底层命令实现与版本发现机制。

快速开始：安装最新 Python

如果系统已经安装了 Python，uv 会检测并使用它，无需任何配置；但 uv 也可以自己安装和管理 Python 版本，甚至能按需自动安装缺失的版本——你不需要先装好 Python 就能开始使用 uv。

安装最新的 Python 版本：

$ uv python install

需要注意的分布事实：Python 官方并不发布可分发的二进制构建（distributable binaries）。因此 uv 使用的是 Astral 的 python-build-standalone 项目的发行版。更多发行版细节可参考 Python 版本概念文档。

安装完成后，该版本会被 uv 的所有命令自动使用。uv 同时会把安装好的版本的可执行文件加入你的 PATH：

$ python3.13

默认情况下，uv 只安装带版本号的可执行文件（如 python3.13）。如果你还希望得到通用的 python 和 python3 可执行文件，可以加上实验性的 --default 选项：

$ uv python install --default

关于可执行文件安装的更多细节（目标目录、--force 覆盖规则、补丁版本优先策略等），可参考 Python 可执行文件安装说明。从仓库的存储文档看，Unix 下这些可执行文件默认安装到 ~/.local/bin（例如 python3.13），说明见 存储参考。如果 ~/.local/bin 不在 PATH 中，可以用 uv python update-shell 修改 shell 配置；其入口实现位于 update_shell.rs。

安装指定版本与多版本并存

安装特定的 Python 版本：

$ uv python install 3.12

一次安装多个 Python 版本：

$ uv python install 3.11 3.12

安装替代的 Python 实现，例如 PyPy：

$ uv python install pypy@3.10

uv python install 支持的请求格式远不止版本号。结合 Python 版本概念文档，--python 标志和 uv python install 支持的格式包括：

• <version>（如 3、3.12、3.12.3）
• <version-specifier>（如 >=3.12,<3.13，安装满足约束的版本）
• <version><short-variant>（如 3.13t、3.12.0d）
• <version>+<variant>（如 3.13+freethreaded、3.12.0+debug、3.14+gil）
• <implementation>（如 cpython 或缩写 cp）
• <implementation>@<version>（如 cpython@3.12）
• <implementation><version>（如 cpython3.12 或 cp312）
• <implementation><version-specifier>（如 cpython>=3.12,<3.13）
• <implementation>-<version>-<os>-<arch>-<libc>（如 cpython-3.12.3-macos-aarch64-none）

此外还可以用 <executable-path>、<executable-name> 或 <install-dir> 直接请求某个系统解释器（这类本地解释器格式不能用于 uv python install 的远程安装）。

两个实用的行为细节：

• 如果当前目录存在 .python-version 文件（可由 uv python pin 创建），不带参数执行 uv python install 时会安装该文件中列出的版本；
• 如果一个项目需要多个 Python 版本，可以定义 .python-versions 文件列出多个版本，uv python install 会全部安装。

!!! note 每个 uv 发行版内置的可下载 Python 版本列表是冻结的。要安装更新的 Python 版本，可能需要先升级 uv 本身。

重新安装 Python（--reinstall）

要重新安装 uv 托管的 Python 版本，使用 --reinstall 标志：

$ uv python install --reinstall

这会重新安装所有此前已安装的 Python 版本。由于 Python 发行版中会持续加入改进（bug 修复、构建优化），即使版本号不变，重新安装也可能解决已有问题。

从源码实现看，这一行为在 install.rs 中有明确体现：当传入 reinstall 为真且没有指定具体目标时，命令会把所有已安装的 Python 版本都纳入重装计划（// On bare --reinstall, reinstall all Python versions，见 install.rs#L394-L395）；而对于"升级"场景，源码特意区分了"重装最新补丁版本，而不是每个匹配的补丁版本"（install.rs#L494-L495）。

install 函数本身的完整签名（install.rs#L183）也揭示了该命令支持的全部选项维度，与文档中的命令行选项一一对应：

pub(crate) async fn install(
    project_dir: &Path,
    install_dir: Option<PathBuf>,
    targets: Vec<String>,
    reinstall: bool,
    upgrade: PythonUpgrade,
    bin: Option<bool>,
    registry: Option<bool>,
    force: bool,
    python_install_mirror: Option<String>,
    pypy_install_mirror: Option<String>,
    python_downloads_json_url: Option<String>,
    client_builder: BaseClientBuilder<'_>,
    default: bool,
    python_downloads: PythonDownloads,
    ...
) -> Result<ExitStatus>

例如 force 对应文档中"已存在非 uv 管理的可执行文件时默认不覆盖，加 --force 才覆盖"的规则；python_install_mirror / pypy_install_mirror 则支持自定义下载镜像。

查看已安装与可安装的 Python

$ uv python list

uv python list 会同时展示当前可用的版本与 uv 已安装的版本（带下载状态标记），是排查"为什么 uv 选择了某个解释器"的第一步。实现入口位于 list.rs#L57。

自动 Python 下载

要使用 uv，你并不需要先显式安装 Python。默认情况下，uv 会在需要时自动下载 Python 版本。例如，以下命令会在 Python 3.12 未安装时自动下载它：

$ uvx python@3.12 -c "print('hello world')"

即使没有请求特定版本，uv 也会按需下载最新版。例如，如果系统上不存在任何 Python 版本，下面的命令会先安装 Python 再创建虚拟环境：

$ uv venv

如果需要更强的控制，可以禁用自动下载。方法有两条（见 Python 版本概念文档）：

• 在配置中设置 python-downloads 选项为 manual 或 never；
• 或在任意 uv 命令上传入 --no-python-downloads 标志。

使用系统已有的 Python

当系统上已存在 Python 安装时，uv 会直接使用它们：若系统 Python 满足当前命令调用的要求，uv 就会选用它，无需任何配置。具体的发现（discovery）机制——包括从 PATH、标准安装位置、.python-version 文件逐级搜索——详见 Python 版本发现说明。

如果想强制 uv 只使用系统 Python、忽略 uv 托管的版本，提供 --no-managed-python 标志；反向操作（强制只使用托管版本）则使用 --managed-python：

$ uv python list --no-managed-python

这两个标志与 python-preference 配置项配合使用，用于在"托管版本优先"与"系统版本优先"之间切换策略。

升级 Python 补丁版本（preview）

!!! important 对 Python 补丁版本的升级支持目前处于 preview（预览） 阶段，行为是实验性的，可能随版本变化。

将某个 Python 版本升级到最新的受支持补丁版本：

$ uv python upgrade 3.12

升级所有 uv 托管的 Python 版本：

$ uv python upgrade

几个关键约束（来自 Python 版本概念文档）：

• 升级只支持 uv 托管的 Python 版本，且目前不支持 PyPy、GraalPy 和 Pyodide；
• 升级只允许同 minor 版本内的补丁升级（如 3.13.4 → 3.13.5），不允许跨 minor 版本（3.12 → 3.13），因为跨 minor 版本可能影响依赖解析；
• 升级后 uv 会优先使用新版本，但旧版本会被保留，因为已有的虚拟环境可能仍在引用它；
• 使用旧版本的虚拟环境会被自动升级到新补丁版本——该机制通过 minor 版本目录实现，例如 ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none；但若虚拟环境是显式指定补丁版本创建的（如 uv venv -p 3.10.8），则不会被透明升级。

小结与延伸

uv python 命令组把"安装解释器"这件传统上依赖发行版包管理器或 pyenv 的事，变成了 uv 的一等能力：uv python install 负责安装（支持多版本、替代实现、--default、--reinstall），uv python list 负责查看，uv python upgrade 负责补丁版本滚动升级，而"自动按需下载"机制则让大多数用户完全无需显式管理 Python。

核心命令的实现都集中在 crates/uv/src/commands/python/ 目录下：install.rs、list.rs、find.rs、pin.rs、uninstall.rs 等，对应 uv python 下的各子命令；下载元数据由 download-metadata.json 描述，这是"每个 uv 发行版冻结可用版本列表"这一行为的直接体现。

下一步，可继续阅读 Python 版本概念文档 了解完整的版本请求语法、发现机制与存储布局，以及 Python 存储参考 了解托管 Python 与可执行文件的落盘位置，最后结合 脚本运行指南 学习如何用 uv 直接运行 Python 脚本。