Python 版本
Python版本由Python解释器（即python可执行文件）、标准库和其他支持文件组成。
托管和系统Python安装
由于系统通常已安装Python环境，uv支持发现Python版本。同时，uv也支持自行安装Python版本。为区分这两种Python安装方式，uv将自身安装的Python版本称为托管Python安装，其他所有Python安装则称为系统Python安装。
注意
uv不会区分由操作系统安装的Python版本与由其他工具安装和管理的版本。例如，如果Python安装是通过pyenv管理的，在uv中仍会被视为系统Python版本。
请求版本
可以通过在大多数uv命令中使用--python标志来请求特定的Python版本。例如，在创建虚拟环境时：
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)- - - - 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 发行版。
提示
默认情况下，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可执行文件的功能目前处于预览阶段，这意味着该行为是实验性的，可能会发生变化。
要将Python可执行文件安装到您的PATH中，请提供--preview选项：
这将安装一个指定版本的Python可执行文件到~/.local/bin目录下，例如安装为python3.12。
提示
如果 ~/.local/bin 不在你的 PATH 环境变量中，可以通过运行 uv tool update-shell 命令将其添加进去。
要安装python和python3可执行文件，请包含--default选项：
在安装Python可执行文件时，uv只会覆盖由uv管理的现有可执行文件——例如，如果~/.local/bin/python3.12已存在，uv在没有--force标志的情况下不会覆盖它。
uv会更新它管理的可执行文件。但默认情况下，它会优先选择每个Python小版本的最新补丁版本。例如：
$ uv python install 3.12.7 --preview # Adds `python3.12` to `~/.local/bin`
$ uv python install 3.12.6 --preview # Does not update `python3.12`
$ uv python install 3.12.8 --preview # Updates `python3.12` to point to 3.12.8
项目Python版本
uv在执行项目命令时会遵循pyproject.toml文件中requires-python定义的Python版本要求。系统将使用第一个符合要求的Python版本，除非通过.python-version文件或--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解释器，在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 设置可以在持久化配置文件中修改以改变默认行为，或者在任何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版本。
默认情况下，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 quirks
文档。此外，某些平台可能不受支持（例如，目前尚未提供针对ARM架构musl Linux的发行版）。
PyPy 发行版
PyPy发行版由PyPy项目提供。