跳至主要內容

Python 版本管理

HSXISAWD2026/3/20大约 7 分钟uvuvPython版本管理pyenv

Python 版本管理

使用 uv 轻松管理多个 Python 版本

概述

uv 内置了完整的 Python 版本管理功能，可以替代 pyenv、python-build 等工具。它能够自动下载、安装和管理多个 Python 版本。

核心优势

特性描述
自动下载需要的 Python 版本会自动下载
预编译二进制使用 python-build-standalone 预编译版本
跨平台支持 Linux、macOS、Windows
多版本共存可以同时安装多个版本
项目绑定使用 .python-version 固定项目版本

安装 Python 版本

基本安装

# 安装特定版本
uv python install 3.11
uv python install 3.12
uv python install 3.12.1

# 安装多个版本
uv python install 3.10 3.11 3.12

# 安装最新稳定版
uv python install 3

# 安装最新的特定小版本
uv python install 3.11  # 安装 3.11.x 最新版

版本选择器

# 精确版本
uv python install 3.12.1

# 小版本范围（最新补丁版本）
uv python install 3.12

# 主版本范围（最新小版本）
uv python install 3

# 版本约束
uv python install ">=3.10"
uv python install ">=3.10,<3.12"

安装 PyPy

# 安装 PyPy
uv python install pypy3.10
uv python install pypy@3.10

# 列出可用的 PyPy 版本
uv python list | grep pypy

安装来源

uv 使用 python-build-standalone 项目提供的预编译 Python 二进制文件。

┌─────────────────────────────────────────────────────────────────────────┐
│                      Python 安装来源                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              python-build-standalone                        │      │
│   │     https://github.com/indygreg/python-build-standalone     │      │
│   └─────────────────────────────────────────────────────────────┘      │
│                                │                                        │
│        ┌──────────────────────┬┴──────────────────────┐                │
│        ▼                      ▼                       ▼                │
│   ┌─────────┐           ┌─────────┐            ┌─────────┐            │
│   │  Linux  │           │  macOS  │            │ Windows │            │
│   │ x86_64  │           │  arm64  │            │  x86_64 │            │
│   │ aarch64 │           │  x86_64 │            │         │            │
│   └─────────┘           └─────────┘            └─────────┘            │
│                                                                         │
│   预编译、优化过的 Python 二进制文件，无需编译                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

列出 Python 版本

查看可用版本

# 列出所有可用版本（可下载）
uv python list

# 示例输出
cpython-3.13.0+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.13.0-linux-x86_64-gnu                 <download available>
cpython-3.12.4-linux-x86_64-gnu                 /home/user/.local/share/uv/python/cpython-3.12.4-linux-x86_64-gnu/bin/python3.12
cpython-3.12.3-linux-x86_64-gnu                 <download available>
cpython-3.11.9-linux-x86_64-gnu                 /home/user/.local/share/uv/python/cpython-3.11.9-linux-x86_64-gnu/bin/python3.11
...
pypy-3.10.14-linux-x86_64-gnu                   <download available>

只显示已安装版本

uv python list --only-installed

# 示例输出
cpython-3.12.4-linux-x86_64-gnu    /home/user/.local/share/uv/python/cpython-3.12.4-linux-x86_64-gnu/bin/python3.12
cpython-3.11.9-linux-x86_64-gnu    /home/user/.local/share/uv/python/cpython-3.11.9-linux-x86_64-gnu/bin/python3.11
cpython-3.10.14-linux-x86_64-gnu   /home/user/.local/share/uv/python/cpython-3.10.14-linux-x86_64-gnu/bin/python3.10

查看系统 Python

# 包含系统 Python
uv python list --all-versions

# 只显示系统 Python
uv python list --only-system

固定项目 Python 版本

使用 uv python pin

# 固定项目使用的 Python 版本
uv python pin 3.11

# 创建 .python-version 文件
cat .python-version
# 3.11

# 固定精确版本
uv python pin 3.11.9

.python-version 文件

# 文件内容示例
3.11

# 或精确版本
3.11.9

# 或版本约束
>=3.10

# 支持多种格式
3.12
cpython-3.12
cpython@3.12

版本查找优先级

当运行 uv run 或 uv sync 时，uv 按以下顺序查找 Python 版本：

┌─────────────────────────────────────────────────────────────────────────┐
│                    Python 版本查找优先级                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   1. UV_PYTHON 环境变量                                                 │
│      │                                                                  │
│      ▼                                                                  │
│   2. 命令行 --python 参数                                               │
│      │                                                                  │
│      ▼                                                                  │
│   3. .python-version 文件                                               │
│      │                                                                  │
│      ▼                                                                  │
│   4. pyproject.toml 中的 requires-python                                │
│      │                                                                  │
│      ▼                                                                  │
│   5. uv 管理的 Python 版本                                              │
│      │                                                                  │
│      ▼                                                                  │
│   6. 系统 Python                                                        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

查找 Python 安装

uv python find

# 查找符合条件的 Python
uv python find 3.11

# 示例输出
/home/user/.local/share/uv/python/cpython-3.11.9-linux-x86_64-gnu/bin/python3.11

# 查找任意 Python 3
uv python find 3

# 查找满足约束的 Python
uv python find ">=3.10"

与项目配合

# 项目目录中查找
cd myproject
uv python find
# 返回满足 pyproject.toml 和 .python-version 要求的 Python

# 验证版本
$(uv python find) --version

卸载 Python 版本

基本卸载

# 卸载特定版本
uv python uninstall 3.10

# 卸载多个版本
uv python uninstall 3.9 3.10

# 卸载所有版本
uv python uninstall --all

清理未使用的版本

# 查看已安装版本
uv python list --only-installed

# 手动决定卸载哪些
uv python uninstall 3.9

Python 版本与项目

项目级配置

# pyproject.toml
[project]
name = "myproject"
requires-python = ">=3.10"

# .python-version
3.11

创建项目时指定版本

# 使用指定版本创建项目
uv init --python 3.11 myproject

# 创建后自动生成 .python-version
cat myproject/.python-version
# 3.11

创建虚拟环境时指定版本

# 使用特定版本
uv venv --python 3.11

# 自动下载不存在的版本
uv venv --python 3.13
# Python 3.13 将自动下载

# 使用项目要求的版本
uv venv
# 读取 .python-version 或 pyproject.toml

自动下载行为

配置自动下载

# 环境变量控制
UV_PYTHON_DOWNLOADS=automatic  # 默认：自动下载
UV_PYTHON_DOWNLOADS=manual     # 需要时提示
UV_PYTHON_DOWNLOADS=never      # 从不下载

# 命令行参数
uv run --python-preference only-managed  # 只使用 uv 管理的 Python
uv run --python-preference only-system   # 只使用系统 Python
uv run --python-preference managed       # 优先 uv 管理的（默认）
uv run --python-preference system        # 优先系统 Python

离线模式

# 完全离线，不下载 Python
UV_PYTHON_DOWNLOADS=never uv sync

# 或
uv sync --python-preference only-system

多版本测试

使用不同版本运行测试

# 在多个版本上测试
for version in 3.10 3.11 3.12; do
    echo "Testing on Python $version"
    uv run --python $version pytest
done

Nox/Tox 集成

# noxfile.py
import nox

@nox.session(python=["3.10", "3.11", "3.12"])
def tests(session):
    session.install("pytest")
    session.install(".")
    session.run("pytest")

# 使用 uv 运行 nox
uv run nox

tox 配置

# tox.ini
[tox]
envlist = py310,py311,py312

[testenv]
deps = pytest
commands = pytest

# 使用 uv 作为 tox 的安装器
uv run tox

与 pyenv 的对比

┌─────────────────────────────────────────────────────────────────────────┐
│                      uv vs pyenv                                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   特性              uv                        pyenv                     │
│   ──────────────────────────────────────────────────────────────────   │
│   安装来源          预编译二进制               源码编译                   │
│   安装速度          极快（下载即用）            慢（需要编译）              │
│   依赖              无                        编译工具链                 │
│   Shell 集成        无需                      需要配置 shell             │
│   全局/本地切换      .python-version          .python-version           │
│   自动切换          通过 uv run               需要 shims                 │
│   与包管理集成       完全集成                  独立工具                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

从 pyenv 迁移

# 1. 保持 .python-version 文件（格式兼容）
cat .python-version
# 3.11.9

# 2. 安装对应版本
uv python install $(cat .python-version)

# 3. 验证
uv python find

# 4. 项目中使用
uv sync
uv run python --version

高级配置

安装目录

# 查看 Python 安装位置
uv python dir
# /home/user/.local/share/uv/python

# 自定义安装目录
UV_PYTHON_INSTALL_DIR=/opt/python uv python install 3.12

镜像配置

# 使用国内镜像下载 Python
# 设置 python-build-standalone 的镜像
UV_PYTHON_INSTALL_MIRROR=https://mirror.example.com/python-build-standalone

# 或在配置文件中
# ~/.config/uv/uv.toml
[python]
install-mirror = "https://mirror.example.com/python-build-standalone"

版本解析策略

# pyproject.toml
[tool.uv]
# 指定确切版本
python-version = "3.11.9"

# 或范围
python-version = ">=3.10,<3.13"

故障排除

常见问题

1. Python 版本找不到

# 检查可用版本
uv python list

# 确保版本已安装
uv python install 3.11

# 检查 .python-version 格式
cat .python-version

2. 下载失败

# 检查网络
curl -I https://github.com/indygreg/python-build-standalone/releases

# 使用代理
HTTPS_PROXY=http://proxy:8080 uv python install 3.12

# 使用离线模式
uv python list --only-installed

3. 与系统 Python 冲突

# 明确使用 uv 管理的 Python
uv run --python-preference only-managed python --version

# 或设置环境变量
UV_PYTHON_PREFERENCE=only-managed

4. 版本约束冲突

# pyproject.toml 要求 >=3.11
# .python-version 指定 3.10

# 解决：确保版本一致
uv python pin 3.11

调试命令

# 查看详细信息
uv python install 3.12 --verbose

# 查看 Python 查找过程
UV_LOG=debug uv python find

# 检查安装路径
ls -la $(uv python dir)

最佳实践

团队协作

  1. 提交 .python-version 文件：确保团队使用相同版本
  2. 在 pyproject.toml 中声明 requires-python：明确版本要求
  3. CI 中安装指定版本：避免环境差异

项目配置示例

# pyproject.toml
[project]
name = "myproject"
requires-python = ">=3.10"

# .python-version
3.11

GitHub Actions 示例

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true

      - name: Install Python
        run: uv python install ${{ matrix.python-version }}

      - name: Run tests
        run: uv run --python ${{ matrix.python-version }} pytest

总结

操作命令
安装版本uv python install 3.12
列出版本uv python list
已安装版本uv python list --only-installed
固定版本uv python pin 3.11
查找版本uv python find 3.11
卸载版本uv python uninstall 3.10

关键要点

  1. uv 自动管理 Python - 无需 pyenv 等额外工具
  2. 使用预编译二进制 - 安装速度极快
  3. 通过 .python-version 固定版本 - 团队一致性
  4. 自动下载 - 需要的版本自动获取

下一步

Default footer
Copyright © 2026 HSXISAWD