跳到内容

Python 版本

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

托管和系统 Python 安装

由于一个系统通常会有一个现有的 Python 安装，uv 支持发现 Python 版本。 然而，uv 也支持自行安装 Python 版本。 为了区分这两种类型的 Python 安装，uv 将其安装的 Python 版本称为托管 Python 安装，并将所有其他 Python 安装称为系统 Python 安装。

注意

uv 不区分操作系统安装的 Python 版本和其他工具安装和管理的 Python 版本。 例如，如果一个 Python 安装由 pyenv 管理，它仍然会被 uv 认为是系统 Python 版本。

请求版本

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

$ uv venv --python 3.11.6

uv 将确保 Python 3.11.6 可用 — 如有必要，下载并安装它 — 然后使用它创建虚拟环境。

支持以下 Python 版本请求格式

  • <版本> (例如，3、3.12、3.12.3)
  • <版本说明符> (例如，>=3.12,<3.13)
  • <实现> (例如，cpython 或 cp)
  • <实现>@<版本> (例如，[email protected])
  • <实现><版本> (例如，cpython3.12 或 cp312)
  • <实现><版本说明符> (例如，cpython>=3.12,<3.13)
  • <实现>-<版本>-<操作系统>-<架构>-<libc> (例如，cpython-3.12.3-macos-aarch64-none)

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

  • <可执行文件路径> (例如，/opt/homebrew/bin/python3)
  • <可执行文件名称> (例如，mypython3)
  • <安装目录> (例如，/some/environment/)

默认情况下，如果 uv 在系统上找不到 Python 版本，它将自动下载。 可以使用 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 版本。

重要

每个 uv 版本的可用 Python 版本都是冻结的。 要安装新的 Python 版本，您可能需要升级 uv。

安装 Python 可执行文件

默认情况下，uv 会将 Python 可执行文件安装到您的 PATH 中，例如，uv python install 3.12 会将 Python 可执行文件安装到 ~/.local/bin 中，例如作为 python3.12。

提示

如果 ~/.local/bin 不在您的 PATH 中，您可以使用 uv tool 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 版本

重要

对升级 Python 版本的支持处于预览状态。 这意味着该行为是实验性的，可能会发生变化。

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

当前不支持 PyPy 和 GraalPy 的升级。

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 python install 3.12 --preview，则使用该 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 版本，除非以其他方式请求了版本，例如，通过 .python-version 文件或 --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 解释器，在 macOS 和 Linux 上为 python、python3 或 python3.x，在 Windows 上为 python.exe。
  • 在 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 版本与请求匹配，并且将使用该预发布版本。

如果 Python 预发布版本可用并与请求匹配，uv 将不会下载稳定的 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 安装。

默认情况下，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 发行版是独立的、高度可移植且性能良好的。 虽然 Python 可以从源代码构建，就像 pyenv 等工具一样，但这样做需要预安装的系统依赖项，并且创建优化的、性能良好的构建（例如，启用 PGO 和 LTO）非常慢。

这些发行版有一些行为怪癖，通常是由于可移植性造成的； 有关详细信息，请参阅python-build-standalone 怪癖文档。 此外，某些平台可能不支持（例如，尚未提供 ARM 上 musl Linux 的发行版）。

PyPy 发行版

PyPy 发行版由 PyPy 项目提供。

在 Windows 注册表中注册

在 Windows 上，安装托管的 Python 版本会将它们注册到 Windows 注册表中，如 PEP 514 中定义的那样。

安装后，可以使用 py 启动器选择 Python 版本，例如

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

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