Python 版本
Python 版本由 Python 解释器（即 python 可执行文件）、标准库和其他支持文件组成。
托管和系统 Python 安装
由于系统中通常已安装 Python，uv 支持发现 Python 版本。不过，uv 也支持自行安装 Python 版本。为区分这两种 Python 安装类型，uv 将其安装的 Python 版本称为_托管_ Python 安装，而将所有其他 Python 安装称为_系统_ Python 安装。
注意
uv 不会区分操作系统安装的 Python 版本与其他工具安装和管理的 Python 版本。例如，如果使用 pyenv 管理 Python 安装，在 uv 中它仍会被视为_系统_ Python 版本。
请求特定版本
在大多数 uv 命令中，可以使用 --python 标志请求特定的 Python 版本。例如，在创建虚拟环境时：
uv 会确保 Python 3.11.6 可用（必要时会下载并安装），然后使用它创建虚拟环境。
支持以下 Python 版本请求格式：
<版本>（例如，3、3.12、3.12.3）<版本说明符>（例如，>=3.12,<3.13）<实现>（例如，cpython或cp）<实现>@<版本>（例如，cpython@3.12）<实现><版本>（例如，cpython3.12或cp312）<实现><版本说明符>（例如，cpython>=3.12,<3.13）<实现>-<版本>-<操作系统>-<架构>-<C 库>（例如，cpython-3.12.3-macos-aarch64-none）
此外，可以通过以下方式请求特定的系统 Python 解释器：
<可执行文件路径>（例如，/opt/homebrew/bin/python3）<可执行文件名>（例如，mypython3）<安装目录>（例如，/some/environment/）
默认情况下，如果系统中找不到 Python 版本，uv 将自动下载。此行为可以通过
python-downloads 选项禁用。
Python 版本文件
可以使用 .python-version 文件来创建默认的 Python 版本请求。uv 会在工作目录及其每个父目录中搜索 .python-version 文件。如果未找到，则 uv 会检查用户级配置目录。上述任何请求格式都可以使用，但为了与其他工具的互操作性，建议使用版本号。
可以使用uv python pin 命令在当前目录中创建 .python-version 文件。
可以使用uv python pin --global 命令在用户配置目录中创建全局 .python-version 文件。
可以使用 --no-config 禁用对 .python-version 文件的搜索。
uv 不会在项目或工作区边界之外搜索 .python-version 文件（用户配置目录除外）。
安装 Python 版本
uv 集成了适用于 macOS、Linux 和 Windows 系统的可下载 CPython 和 PyPy 发行版列表。
Tip
默认情况下，Python 版本会根据需要自动下载，无需使用 uv python install 命令。
要安装特定版本的 Python：
要安装最新的补丁版本：
要安装满足约束条件的版本：
要安装多个版本：
要安装特定的实现版本：
除了用于请求本地解释器（如文件路径）的格式外，所有 Python 版本请求格式 均受支持。
默认情况下，uv python install 会验证是否已安装受管理的 Python 版本，或者安装最新版本。如果存在 .python-version 文件，uv 将安装该文件中列出的 Python 版本。需要多个 Python 版本的项目可以定义一个 .python-versions 文件。如果存在该文件，uv 将安装文件中列出的所有 Python 版本。
Important
每个 uv 版本可用的 Python 版本是固定的。要安装新的 Python 版本，可能需要升级 uv。
安装 Python 可执行文件
Important
安装 Python 可执行文件的功能处于 预览 阶段，这意味着其行为是试验性的，可能会发生变化。
要将 Python 可执行文件安装到 PATH 中，请提供 --preview 选项：
这将把请求版本的 Python 可执行文件安装到 ~/.local/bin 中，例如 python3.12。
Tip
如果 ~/.local/bin 不在你的 PATH 中，你可以使用 uv tool update-shell 将其添加进去。
要安装 python 和 python3 可执行文件，请包含 --default 选项：
安装 Python 可执行文件时，uv 仅会覆盖由 uv 管理的现有可执行文件 —— 例如，如果 ~/.local/bin/python3.12 已存在，没有 --force 标志的情况下，uv 不会覆盖它。
uv 会更新由其管理的可执行文件。不过，默认情况下，它会优先选择每个 Python 次版本的最新补丁版本。例如：
$ uv python install 3.12.7 --preview # 将 `python3.12` 添加到 `~/.local/bin`
$ uv python install 3.12.6 --preview # 不更新 `python3.12`
$ uv python install 3.12.8 --preview # 将 `python3.12` 更新为指向 3.12.8
项目 Python 版本
在项目命令调用期间，uv 会遵循 pyproject.toml 文件中 requires-python 里定义的 Python 要求。除非另外请求了某个版本，例如通过 .python-version 文件或 --python 标志，否则将使用与该要求兼容的第一个 Python 版本。
查看可用的 Python 版本
要列出已安装和可用的 Python 版本：
要筛选 Python 版本，可提供请求，例如，要显示所有 Python 3.13 解释器：
或者，要显示所有 PyPy 解释器：
默认情况下，其他平台的下载版本和旧的补丁版本会被隐藏。
要查看所有版本：
要查看其他平台的 Python 版本：
要排除下载版本，仅显示已安装的 Python 版本：
更多详细信息，请参阅uv python list 参考文档。
查找 Python 可执行文件
要查找 Python 可执行文件，使用 uv python find 命令：
默认情况下，这将显示第一个可用 Python 可执行文件的路径。有关可执行文件查找方式的详细信息，请参阅查找规则。
此接口还支持多种请求格式，例如，要查找版本为 3.11 或更新版本的 Python 可执行文件：
默认情况下，uv python find 将包含虚拟环境中的 Python 版本。如果在工作目录或任何父目录中找到 .venv 目录，或者设置了 VIRTUAL_ENV 环境变量，它将优先于 PATH 上的任何 Python 可执行文件。
要忽略虚拟环境，使用 --system 标志：
发现 Python 版本
在查找 Python 版本时，会检查以下位置：
- UV_PYTHON_INSTALL_DIR 中由 uv 管理的 Python 安装。
- 在 macOS 和 Linux 系统上，PATH 中的 python、python3 或 python3.x Python 解释器；在 Windows 系统上，则为 python.exe。
- 在 Windows 系统上，Windows 注册表中的 Python 解释器以及 Microsoft Store 中的 Python 解释器（请参阅 py --list-paths），前提是它们与请求的版本匹配。
在某些情况下，uv 允许使用虚拟环境中的 Python 版本。在这种情况下，在按照上述方式查找安装之前，会先检查虚拟环境的解释器是否与请求兼容。有关详细信息，请参阅与 pip 兼容的虚拟环境发现文档。
在执行发现过程时，不可执行文件将被忽略。会查询每个发现的可执行文件的元数据，以确保其符合请求的 Python 版本。如果查询失败，将跳过该可执行文件。如果可执行文件满足请求，则会使用它，而不会检查其他可执行文件。
在查找由 uv 管理的 Python 版本时，uv 会优先选择较新的版本。在查找系统 Python 版本时，uv 将使用第一个兼容的版本，而不是最新版本。
如果在系统上找不到 Python 版本，uv 将检查是否有可下载的兼容的由 uv 管理的 Python 版本。
Python 预发布版本
默认情况下，不会选择 Python 预发布版本。如果没有其他符合要求的可用安装版本，将使用 Python 预发布版本。例如，如果只有预发布版本可用，则会使用该版本，否则将使用稳定发布版本。同样，如果提供了预发布 Python 可执行文件的路径，且没有其他 Python 版本符合要求，则将使用预发布版本。
如果有可用的预发布 Python 版本且符合要求，uv 不会下载稳定的 Python 版本。
禁用自动下载 Python
默认情况下，uv 会在需要时自动下载 Python 版本。
可以使用python-downloads选项来禁用此行为。默认设置为automatic；设置为manual则仅在uv python install期间允许下载 Python。
Tip
可以在持久配置文件中设置python-downloads，以更改默认行为，或者可以将--no-python-downloads标志传递给任何 uv 命令。
要求使用或禁用托管的 Python 版本
默认情况下，uv 将尝试使用系统上找到的 Python 版本，仅在必要时下载托管的 Python 版本。要忽略系统 Python 版本，仅使用托管的 Python 版本，请使用--managed-python标志：
同样，要忽略托管的 Python 版本，仅使用系统 Python 版本，请使用--no-managed-python标志：
要在配置文件中更改 uv 的默认行为，请使用python-preference设置。
调整 Python 版本偏好
python-preference 设置决定是优先使用系统中已有的 Python 安装，还是使用由 uv 下载并安装的 Python。
默认情况下，python-preference 设置为 managed，这表示优先使用托管的 Python 安装，而非系统 Python 安装。不过，系统 Python 安装仍优先于下载托管的 Python 版本。
以下是其他可用选项：
- only-managed：仅使用托管的 Python 安装；从不使用系统 Python 安装。等同于 --managed-python。
- system：优先使用系统 Python 安装，而非托管的 Python 安装。
- only-system：仅使用系统 Python 安装；从不使用托管的 Python 安装。等同于 --no-managed-python。
注意
可以在不更改偏好的情况下禁用自动下载 Python 版本。
Python 实现支持
uv 支持 CPython、PyPy 和 GraalPy 这几种 Python 实现。如果某个 Python 实现不受支持，uv 将无法发现其解释器。
可以使用全称或简称来指定实现：
- CPython：cpython、cp
- PyPy：pypy、pp
- GraalPy：graalpy、gp
实现名称的指定不区分大小写。
有关支持格式的更多详细信息，请参阅请求 Python 版本文档。
托管的 Python 发行版
uv 支持下载并安装 CPython 和 PyPy 发行版。
CPython 发行版
由于 Python 并未发布官方可分发的 CPython 二进制文件，因此 uv 使用的是 Astral 的
python-build-standalone 项目预先构建的发行版。
python-build-standalone 也被许多其他 Python 项目所使用，例如
Rye、Mise 以及
bazelbuild/rules_python。
uv 的 Python 发行版是自包含的，具有高度可移植性和高性能。虽然可以像在 pyenv 等工具中那样从源代码构建 Python，但这样做需要预先安装系统依赖项，而且创建优化的高性能构建（例如，启用 PGO 和 LTO）的速度非常慢。
这些发行版存在一些行为怪癖，通常是由于可移植性导致的；有关详细信息，请参阅
python-build-standalone 怪癖 文档。此外，某些平台可能不受支持（例如，目前还没有适用于 ARM 架构上 musl Linux 的发行版）。
PyPy 发行版
PyPy 发行版由 PyPy 项目提供。