基于 UV 的 Python 版本管理

type

Post

status

Published

date

Oct 11, 2025

slug

uv-python-venv-version-control

summary

基于uv进行python版本及虚拟环境管理教程。

概念

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

托管和系统 Python 安装

由于系统通常已经安装了 Python,uv 支持发现 Python 版本。但 uv 也支持自己安装 Python 版本。为了区分这两种类型:

托管 Python 安装: uv 安装的 Python 版本

系统 Python 安装: 其他所有 Python 安装(包括操作系统或其他工具如 pyenv 安装的)

请求版本

使用 --python 标志请求特定 Python 版本:

uv 会确保 Python 3.11.6 可用(必要时自动下载安装),然后用它创建虚拟环境。

支持的请求格式

<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)

<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 会在工作目录及其父目录中搜索此文件。如果找不到,会检查用户级配置目录。

创建版本文件

使用 --no-config 可禁用 .python-version 文件的发现。

安装 Python 版本

uv 内置了 macOS、Linux 和 Windows 的 CPython 和 PyPy 发行版下载列表。

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

安装示例

重要: 可用的 Python 版本在每个 uv 版本中固定。要安装新的 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 可执行文件:

升级 Python 版本

重要: Python 版本升级支持处于预览阶段。

uv 允许透明升级 Python 补丁版本(如 3.13.4 到 3.13.5),但不支持跨次要版本升级(如 3.12 到 3.13)。

升级后,uv 会优先使用新版本,但会保留旧版本,因为现有虚拟环境可能仍在使用。

项目 Python 版本

uv 在项目命令调用期间会遵守 pyproject.toml 文件中 requires-python 定义的 Python 要求。将使用与要求兼容的第一个 Python 版本,除非通过 .python-version 文件或 --python 标志另行请求。

查看可用的 Python 版本

查找 Python 可执行文件

Python 版本发现规则

搜索 Python 版本时,会按以下顺序检查:

UV_PYTHON_INSTALL_DIR 中的托管 Python 安装

PATH 中的 Python 解释器(macOS/Linux: python, python3, python3.x; Windows: python.exe)

Windows 注册表和 Microsoft Store 中的 Python 解释器(Windows)

发现时会跳过非可执行文件。每个发现的可执行文件都会查询元数据以确保满足请求的 Python 版本。

特殊 Python 变体

预发布版本

Python 预发布版本默认不会被选择。只有在没有其他可用安装匹配请求时才会使用。

自由线程 Python

uv 支持 CPython 3.13+ 中的自由线程 Python 变体。

自由线程 Python 版本默认不会被选择。只有明确请求时才会选择,例如使用 3.13t 或 3.13+freethreaded。

调试 Python 变体

uv 支持发现和安装 Python 的调试构建版本。

重要: Python 的调试构建速度较慢,不适合一般使用。

可以使用 3.13d 或 3.13+debug 明确请求调试构建。

禁用自动 Python 下载

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

python-downloads 选项可用于禁用此行为。默认设置为 automatic; 设置为 manual 仅允许在 uv python install 期间下载 Python。

提示: 可以在持久配置文件中设置 python-downloads,或使用 --no-python-downloads 标志。

要求或禁用托管 Python 版本

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

调整 Python 版本偏好

python-preference 设置确定是优先使用系统上已有的 Python 安装,还是 uv 下载安装的。

默认值: managed - 优先使用托管 Python,但仍然优先使用系统 Python 而不是下载新版本。

其他选项:

only-managed: 仅使用托管 Python 安装

system: 优先使用系统 Python 安装

only-system: 仅使用系统 Python 安装

Python 实现支持

uv 支持以下 Python 实现:

CPython: cpython, cp

PyPy: pypy, pp

GraalPy: graalpy, gp

Pyodide: pyodide

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

托管 Python 发行版

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

CPython 发行版

由于 Python 不发布官方的可分发 CPython 二进制文件,uv 使用 Astral python-build-standalone 项目的预构建发行版。这些发行版自包含、高度可移植且高性能。

PyPy 发行版

由 PyPy 项目提供。

Pyodide 发行版

由 Pyodide 项目提供。Pyodide 是针对 WebAssembly / Emscripten 平台的 CPython 移植版本。

aarch64 上的透明 x86_64 仿真

macOS 和 Windows 都支持通过透明仿真在 aarch64 上运行 x86_64 二进制文件(Rosetta 2 或 Windows on ARM)。可以在 aarch64 上使用 x86_64 uv,也可以使用 x86_64 Python 解释器。但 Python 解释器需要其架构的包,要么全部 x86_64,要么全部 aarch64。

Windows 注册表注册

在 Windows 上,安装托管 Python 版本时会按照 PEP 514 的定义在 Windows 注册表中注册。

安装后,可以使用 py 启动器选择 Python 版本:

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