3.12 Python 版本
11 分钟阅读
3.12 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 版本请求格式：
<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）
此外，还可以请求特定的系统 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：
| |
安装最新的补丁版本：
| |
安装满足约束的版本：
| |
安装多个版本：
| |
安装特定实现：
| |
支持所有 Python 版本请求格式，但用于请求本地解释器（例如文件路径）的格式除外。
默认情况下，uv python install 会验证某个受管 Python 版本已安装，或安装最新版本。如果存在 .python-version 文件，uv 会安装该文件中列出的 Python 版本。需要多个 Python 版本的项目可以定义 .python-versions 文件。如果存在该文件，uv 会安装其中列出的所有 Python 版本。
重要
每个 uv 版本可用的 Python 版本是固定的。要安装新的 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 选项：
| |
安装 Python 可执行文件时，uv 只会覆盖由 uv 管理的现有可执行文件 —— 例如如果 ~/.local/bin/python3.12 已存在，没有 --force 标志时 uv 不会覆盖它。
uv 会更新它管理的可执行文件。不过默认情况下它会优先使用每个 Python 次要版本的最新补丁版本。例如：
| |
升级 Python 版本
重要
升级仅支持 uv 管理的 Python 版本。
目前不支持升级 PyPy、GraalPy 和 Pyodide。
uv 允许把 Python 版本透明升级到最新补丁版本，例如从 3.13.4 升级到 3.13.5。uv 不允许跨次要版本透明升级，例如从 3.12 升级到 3.13，因为更改次要版本可能影响依赖解析。
uv 管理的 Python 版本可以用 python upgrade 命令升级到最新的受支持补丁版本：
要把某个 Python 版本升级到最新的受支持补丁版本：
| |
升级所有已安装的 Python 版本：
| |
升级之后，uv 会优先使用新版本，但会保留既有版本，因为它可能仍被虚拟环境使用。
使用该 Python 版本的虚拟环境会自动升级到新的补丁版本。
如果虚拟环境是用显式请求的补丁版本创建的，例如 uv venv -p 3.10.8，它不会被透明升级到新版本。
次要版本目录
虚拟环境的自动升级通过一个以 Python 次要版本命名的目录实现，例如：
~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
它是指向特定补丁版本的符号链接（Unix 上）或联接（Windows 上）：
| |
如果该链接被其他工具解析（例如通过规范化 Python 解释器路径），并用于创建虚拟环境，那么该环境不会被自动升级。
项目的 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中的受管 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 版本满足请求，就会使用该预发布版本。
如果有可用的预发布 Python 版本且满足请求，uv 不会改为下载稳定 Python 版本。
自由线程 Python
uv 支持在 CPython 3.13+ 中发现和安装自由线程 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 的调试构建，即启用了调试断言的构建。
重要
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来更改默认行为，也可以给任何 uv 命令传入--no-python-downloads标志。
要求或禁用受管 Python 版本
默认情况下，uv 会尝试使用系统中找到的 Python 版本，只在必要时才下载受管 Python 版本。要忽略系统 Python 版本、只使用受管 Python 版本，请使用 --managed-python 标志：
| |
同样，要忽略受管 Python 版本、只使用系统 Python 版本，请使用 --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 发行版自包含、可移植性强且性能出色。虽然 Python 可以从源码构建（例如像 pyenv 这类工具那样），但这样做需要预装系统依赖，而且创建经过优化、性能出色的构建（例如启用 PGO 和 LTO）非常慢。
这些发行版有一些行为上的特殊之处，通常是可移植性带来的结果；细节请参阅 python-build-standalone 特殊行为文档。
PyPy 发行版
注意
PyPy 版本落后于 CPython，目前只支持到 Python 3.11。
PyPy 发行版由 PyPy 项目提供。
Pyodide 发行版
Pyodide 发行版由 Pyodide 项目提供。
Pyodide 是 CPython 面向 WebAssembly / Emscripten 平台的移植版本。
在 aarch64 上透明模拟 x86_64
macOS 和 Windows 都支持通过透明模拟在 aarch64 上运行 x86_64 二进制文件。这称为 Rosetta 2 或 Windows on ARM（WoA）模拟。可以在 aarch64 上使用 x86_64 的 uv，也可以在 aarch64 上使用 x86_64 的 Python 解释器。两种 uv 二进制文件都可以使用两种 Python 解释器，但 Python 解释器需要其对应架构的包，要么全是 x86_64，要么全是 aarch64。
在 Windows 注册表中注册
在 Windows 上，安装受管 Python 版本会按 PEP 514 的定义把它们注册到 Windows 注册表。
安装之后，可以用 py 启动器选择这些 Python 版本，例如：
| |
卸载时，uv 会移除目标版本的注册表项以及任何损坏的注册表项。