Python 版本

一个 Python 版本由 Python 解释器（即 python 可执行文件）、标准库和其他支持文件组成。

托管 Python 安装与系统 Python 安装

由于系统中通常已存在 Python 安装，uv 支持发现现有的 Python 版本。同时，uv 也支持自行安装 Python 版本。为了区分这两类安装，uv 将其自行安装的 Python 版本称为托管（managed） Python 安装，而将所有其他 Python 安装称为系统（system） Python 安装。

注意

uv 不区分由操作系统安装的 Python 版本与由其他工具管理安装的 Python 版本。例如，如果 Python 安装是由 pyenv 管理的，它在 uv 中仍被视为系统 Python 版本。

请求版本

在大多数 uv 命令中，可以使用 --python 标志请求特定的 Python 版本。例如，在创建虚拟环境时

$ uv venv --python 3.11.6

uv 将确保 Python 3.11.6 可用（必要时进行下载和安装），然后使用它创建虚拟环境。

支持以下 Python 版本请求格式

<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> (例如，[email protected])
<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)

此外，可以通过以下方式请求特定的系统 Python 解释器

<executable-path> (例如，/opt/homebrew/bin/python3)
<executable-name> (例如，mypython3)
<install-dir> (例如，/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 发行版。

提示

默认情况下，Python 版本会根据需要自动下载，无需使用 uv python install。

安装指定版本的 Python

$ uv python install 3.12.3

安装最新的补丁版本

$ uv python install 3.12

安装满足约束的版本

$ uv python install '>=3.8,<3.10'

安装多个版本

$ uv python install 3.9 3.10 3.11

安装特定实现

$ uv python install pypy

支持所有Python 版本请求格式，除了那些用于请求本地解释器（例如文件路径）的格式。

默认情况下，uv python install 会验证托管的 Python 版本是否已安装或安装最新版本。如果存在 .python-version 文件，uv 将安装该文件中列出的 Python 版本。一个需要多个 Python 版本的项目可以定义一个 .python-versions 文件。如果存在，uv 将安装该文件中列出的所有 Python 版本。

重要

可用的 Python 版本在每个 uv 版本发布时即已固定。要安装新的 Python 版本，可能需要升级 uv。

有关已安装 Python 版本存储位置的详细信息，请参阅存储文档。

安装 Python 可执行文件

默认情况下，uv 会将 Python 可执行文件安装到你的 PATH 中。例如，在 Unix 系统上，uv python install 3.12 会将 Python 可执行文件安装到 ~/.local/bin 中（例如 python3.12）。有关目标目录的更多详细信息，请参阅存储文档。

提示

如果 ~/.local/bin 不在你的 PATH 中，可以使用 uv python update-shell 将其添加进去。

要安装 python 和 python3 可执行文件，请包含实验性选项 --default

$ uv python install 3.12 --default

安装 Python 可执行文件时，uv 仅在可执行文件由 uv 管理时才会覆盖它——例如，如果 ~/.local/bin/python3.12 已经存在，除非使用 --force 标志，否则 uv 不会覆盖它。

uv 会更新其管理的执行文件。但是，它默认倾向于每个 Python 小版本的最新补丁版本。例如

$ uv python install 3.12.7  # Adds `python3.12` to `~/.local/bin`
$ uv python install 3.12.6  # Does not update `python3.12`
$ uv python install 3.12.8  # Updates `python3.12` to point to 3.12.8

升级 Python 版本

重要

升级仅支持 uv 管理的 Python 版本。

目前不支持升级 PyPy、GraalPy 和 Pyodide。

uv 允许透明地将 Python 版本升级到最新的补丁版本，例如从 3.13.4 升级到 3.13.5。uv 不允许跨 Python 小版本进行透明升级（例如从 3.12 到 3.13），因为更改小版本可能会影响依赖解析。

可以使用 python upgrade 命令将 uv 管理的 Python 版本升级到最新的受支持补丁版本

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

$ uv python upgrade 3.12

升级所有已安装的 Python 版本

$ uv python upgrade

升级后，uv 将优先使用新版本，但会保留现有版本，因为它可能仍被虚拟环境使用。

使用该 Python 版本的虚拟环境将自动升级到新的补丁版本。

如果虚拟环境是通过显式请求补丁版本创建的（例如 uv venv -p 3.10.8），则不会被透明地升级到新版本。

小版本目录

虚拟环境的自动升级是通过使用一个包含 Python 小版本的目录来实现的，例如

~/.local/share/uv/python/cpython-3.12-macos-aarch64-none

这是一个指向特定补丁版本的符号链接（在 Unix 上）或连接（在 Windows 上）

$ readlink ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none

如果此链接被其他工具解析（例如通过规范化 Python 解释器路径），并用于创建虚拟环境，则它不会自动升级。

项目 Python 版本

在执行项目命令时，uv 将遵守 pyproject.toml 文件中 requires-python 定义的 Python 要求。除非另有请求（例如通过 .python-version 文件或 --python 标志），否则将使用第一个与要求兼容的 Python 版本。

查看可用的 Python 版本

列出已安装和可用的 Python 版本

$ uv python list

要筛选 Python 版本，请提供请求，例如，显示所有 Python 3.13 解释器

$ uv python list 3.13

或者，显示所有 PyPy 解释器

$ uv python list pypy

默认情况下，其他平台的下载和旧补丁版本是隐藏的。

查看所有版本

$ uv python list --all-versions

查看其他平台的 Python 版本

$ uv python list --all-platforms

排除下载项并仅显示已安装的 Python 版本

$ uv python list --only-installed

有关详细信息，请参阅 uv python list 参考。

查找 Python 可执行文件

要查找 Python 可执行文件，请使用 uv python find 命令

$ uv python find

默认情况下，这将显示第一个可用 Python 可执行文件的路径。有关如何发现可执行文件的详细信息，请参阅发现规则。

此接口还支持许多请求格式，例如，查找版本为 3.11 或更新版本的 Python 可执行文件

$ uv python find '>=3.11'

默认情况下，uv python find 将包含来自虚拟环境的 Python 版本。如果在工作目录或任何父目录中找到 .venv 目录，或者设置了 VIRTUAL_ENV 环境变量，它将优先于 PATH 上的任何 Python 可执行文件。

要忽略虚拟环境，请使用 --system 标志

$ uv python find --system

Python 版本的发现机制

搜索 Python 版本时，会检查以下位置

UV_PYTHON_INSTALL_DIR 中的托管 Python 安装。
PATH 上作为 python、python3 或 python3.x（macOS 和 Linux 上）或 python.exe（Windows 上）的 Python 解释器。
在 Windows 上，Windows 注册表中的 Python 解释器和 Microsoft Store Python 解释器（请参阅 py --list-paths）中与请求版本匹配的部分。

在某些情况下，uv 允许使用虚拟环境中的 Python 版本。在这种情况下，在执行上述搜索安装之前，将检查虚拟环境的解释器是否与请求兼容。有关详细信息，请参阅与 pip 兼容的虚拟环境发现文档。

在进行发现时，非可执行文件将被忽略。每个被发现的可执行文件都会被查询元数据，以确保它符合请求的 Python 版本。如果查询失败，该可执行文件将被跳过。如果可执行文件满足请求，则直接使用它，而不再检查其他可执行文件。

搜索托管 Python 版本时，uv 将优先使用较新版本。搜索系统 Python 版本时，uv 将使用第一个兼容版本，而不是最新版本。

如果系统上找不到 Python 版本，uv 将检查是否有兼容的托管 Python 版本可供下载。

Python 预发布版本

默认情况下，不会选择 Python 预发布版本。如果有其他符合请求的安装，则不会使用预发布版本。例如，仅当只有预发布版本可用时才会使用它，否则将使用稳定发布版本。同样，如果提供了预发布 Python 可执行文件的路径，则不会有其他 Python 版本匹配请求，此时将使用该预发布版本。

如果有预发布 Python 版本可用并匹配请求，uv 不会转而下载稳定的 Python 版本。

自由线程（Free-threaded）Python

uv 支持发现和安装 CPython 3.13+ 中的自由线程（free-threaded）Python 变体。

对于 Python 3.13，默认情况下不会选择自由线程 Python 版本。仅在显式请求（例如使用 3.13t 或 3.13+freethreaded）时，才会选择自由线程 Python 版本。

对于 Python 3.14+，uv 允许使用自由线程 Python 3.14+ 解释器而无需显式选择。启用 GIL 的 Python 构建版本仍将被优先选择，例如在使用 uv python install 3.14 执行安装时。但是，例如，如果自由线程解释器在 PATH 上先于启用了 GIL 的构建版本出现，则将使用它。

如果系统上同时存在自由线程和启用 GIL 的 Python 版本，并且希望在项目中强制使用启用 GIL 的变体，可以使用 +gil 变体说明符。

Python 调试变体

uv 支持发现和安装 Python 的调试构建（debug builds），即启用了调试断言的版本。

重要

Python 的调试构建版本运行速度较慢，不适合常规使用。

如果没有其他符合请求的安装，则会使用调试构建版本。例如，仅当只有调试版本可用时才会使用它，否则将使用稳定发布版本。同样，如果提供了调试 Python 可执行文件的路径，则不会有其他 Python 版本匹配请求，此时将使用调试版本。

可以通过例如 3.13d 或 3.13+debug 显式请求 Python 的调试构建。

注意

由 uv 安装的 CPython 版本通常会剥离调试符号以减小分发包大小。这些调试构建版本不会剥离调试符号，这在调试具有 C 级调试器的 Python 进程时非常有用。

禁用自动下载 Python

默认情况下，uv 会在需要时自动下载 Python 版本。

可以使用 python-downloads 选项禁用此行为。默认情况下，它设置为 automatic；将其设置为 manual 仅允许在 uv python install 期间下载 Python。

提示

可以在持久配置文件中设置 python-downloads 以更改默认行为，或者将 --no-python-downloads 标志传递给任何 uv 命令。

强制使用或禁用托管 Python 版本

默认情况下，uv 将尝试使用系统上找到的 Python 版本，并仅在必要时下载托管的 Python 版本。要忽略系统 Python 版本，仅使用托管的 Python 版本，请使用 --managed-python 标志

$ uv python list --managed-python

同样，要忽略托管的 Python 版本，仅使用系统 Python 版本，请使用 --no-managed-python 标志

$ uv python list --no-managed-python

要在配置文件中更改 uv 的默认行为，请使用 python-preference 设置。

调整 Python 版本偏好

python-preference 设置决定了是优先使用系统上已有的 Python 安装，还是使用由 uv 下载和安装的安装。

默认情况下，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、Pyodide 和 GraalPy Python 实现。如果不支持某种 Python 实现，uv 将无法发现其解释器。

可以通过长名称或短名称请求这些实现

CPython：cpython，cp
PyPy：pypy，pp
GraalPy：graalpy，gp
Pyodide：pyodide

实现名称请求不区分大小写。

有关支持格式的更多详细信息，请参阅Python 版本请求文档。

托管 Python 发行版

uv 支持下载和安装 CPython、PyPy 和 Pyodide 发行版。

CPython 发行版

由于 Python 官方不发布可分发的 CPython 二进制文件，uv 使用来自 Astral python-build-standalone 项目的预构建发行版。python-build-standalone 也被许多其他 Python 项目使用，例如 Mise 和 bazelbuild/rules_python。

uv 的 Python 发行版是自包含、高度可移植且高性能的。虽然可以像 pyenv 等工具那样从源代码构建 Python，但这样做需要预先安装系统依赖项，并且创建优化的、高性能的构建版本（例如启用 PGO 和 LTO）非常耗时。

这些发行版有一些行为怪癖，通常是可移植性的必然结果；有关详细信息，请参阅 python-build-standalone 怪癖文档。

PyPy 发行版

注意

PyPy 不再积极开发，且仅支持到 Python 3.11 版本

PyPy 发行版由 PyPy 项目提供。

$ uv python install 3.13.1
$ py -V:Astral/CPython3.13.1

卸载时，uv 将删除目标版本的注册表项以及任何损坏的注册表项。