使用 uv 管理 Python 版本

一、什么是 uv？

uv 是由 Astral（Ruff 的开发者）开发的极速 Python 包管理器和环境管理工具。它用 Rust 编写，旨在替代 pip、pip-tools、poetry、pyenv 和 virtualenv 等传统工具，提供统一的、高性能的 Python 工作流。

uv 的核心优势

特性	说明
极速	Rust 编写，安装依赖速度比 pip 快 10-100 倍
统一工具	一个工具替代 pip + pyenv + virtualenv + pip-tools
Python 版本管理	内置 `uv python` 命令，无需 pyenv
兼容 pip	完全兼容 requirements.txt 和 pyproject.toml
全局缓存	智能依赖缓存，大幅节省磁盘空间
跨平台	支持 macOS、Linux、Windows

二、安装 uv

1. 官方推荐安装（跨平台）

bash 复制代码

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 验证安装

bash 复制代码

uv --version
# 输出类似：uv 0.6.0

3. 配置环境变量（可选但推荐）

安装后，uv 通常会自动添加到 PATH。如果未生效，手动添加：

bash 复制代码

# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

三、使用 uv 管理 Python 版本

uv 内置了 Python 版本管理功能，完全替代 pyenv。

1. 查看可用 Python 版本

bash 复制代码

# 列出所有可安装的 Python 版本
uv python list

# 输出示例：
# cpython-3.13.0-linux-x86_64-gnu     <download available>
# cpython-3.12.7-linux-x86_64-gnu     /usr/bin/python3.12
# cpython-3.11.10-linux-x86_64-gnu    <download available>
# cpython-3.10.15-linux-x86_64-gnu    <download available>
# ...

2. 安装指定 Python 版本

bash 复制代码

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

# 安装指定版本
uv python install 3.11.10

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

# 安装最新版（可能包含预发布版本）
uv python install 3.13

特点：

自动下载官方 CPython 构建，无需编译
安装到 ~/.local/share/uv/python/
不影响系统 Python

3. 查看已安装版本

bash 复制代码

uv python list --only-installed

4. 卸载 Python 版本

bash 复制代码

uv python uninstall 3.11

四、创建和管理虚拟环境

1. 创建虚拟环境（自动选择 Python 版本）

bash 复制代码

# 使用默认 Python 创建
uv venv

# 指定 Python 版本创建
uv venv --python 3.11

# 指定 Python 路径创建
uv venv --python /usr/bin/python3.12

# 指定目录名
uv venv myenv

2. 激活虚拟环境

bash 复制代码

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3. 使用 uv run（推荐方式，无需手动激活）

uv 最强大的特性之一是 uv run，它可以在不激活虚拟环境的情况下直接运行：

bash 复制代码

# 在默认虚拟环境中运行脚本
uv run python script.py

# 指定 Python 版本运行（自动创建临时环境）
uv run --python 3.11 python script.py

# 运行模块
uv run python -m pytest

# 运行命令
uv run flask run

五、依赖管理

1. 安装包

bash 复制代码

# 安装单个包
uv pip install requests

# 安装指定版本
uv pip install requests==2.31.0

# 安装开发依赖
uv pip install pytest --dev

# 从 requirements.txt 安装
uv pip install -r requirements.txt

2. 导出依赖

bash 复制代码

# 导出当前环境依赖
uv pip freeze > requirements.txt

# 使用 pyproject.toml 管理（推荐）
uv pip compile pyproject.toml -o requirements.txt

3. 使用 pyproject.toml（现代 Python 标准）

创建 pyproject.toml：

toml 复制代码

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31.0",
    "numpy>=1.24.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "black>=23.0",
]

然后使用：

bash 复制代码

# 从 pyproject.toml 安装
uv pip install -e .

# 安装开发依赖
uv pip install -e ".[dev]"

# 锁定依赖版本（生成 uv.lock）
uv pip compile pyproject.toml -o requirements.txt

六、完整工作流示例

场景：启动一个新项目

bash 复制代码

# 1. 创建项目目录
mkdir my-project && cd my-project

# 2. 创建 pyproject.toml
cat > pyproject.toml << 'EOF'
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100",
    "uvicorn>=0.23",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "httpx>=0.24",
]
EOF

# 3. 创建虚拟环境（自动使用 pyproject.toml 中的 requires-python）
uv venv

# 4. 安装依赖（包括开发依赖）
uv pip install -e ".[dev]"

# 5. 运行项目
uv run python -m uvicorn main:app --reload

# 6. 运行测试
uv run pytest

# 7. 添加新依赖
uv pip install sqlalchemy
# 然后更新 pyproject.toml

七、高级技巧

1. 全局工具安装

bash 复制代码

# 安装全局工具（类似 pipx）
uv tool install black
uv tool install ruff
uv tool install pytest

# 运行全局工具
uv tool run black .
# 或简写
uvx black .

2. 使用 uv.lock 锁定依赖

bash 复制代码

# 生成锁定文件（类似 poetry.lock）
uv pip compile pyproject.toml -o requirements.txt --generate-hashes

# 从锁定文件安装（确保可复现）
uv pip install -r requirements.txt

3. 缓存管理

bash 复制代码

# 查看缓存大小
du -sh ~/.cache/uv

# 清理缓存
uv cache clean

# 清理特定包的缓存
uv cache clean requests

4. 离线模式

bash 复制代码

# 使用本地缓存离线安装
uv pip install --offline requests

八、uv vs pyenv vs poetry 对比

功能	uv	pyenv	poetry
Python 版本管理	✅ 内置	✅ 专用	❌ 需配合 pyenv
虚拟环境管理	✅ 内置	❌ 需 virtualenv	✅ 内置
依赖锁定	✅ 支持	❌ 不支持	✅ 专用 lock 文件
安装速度	🚀 极快	⏳ 慢（需编译）	⚡ 快
包安装	✅ 兼容 pip	❌ 不支持	✅ 专用
工具链复杂度	🟢 单一工具	🟡 多个工具	🟡 专用格式

九、常见问题

Q1: uv 会替代系统 Python 吗？

不会。uv 将 Python 安装到用户目录（~/.local/share/uv/python/），完全隔离。

Q2: 如何切换默认 Python 版本？

bash 复制代码

# 创建指向特定版本的符号链接
uv python pin 3.12

Q3: 与现有项目兼容吗？

完全兼容。uv pip install 可以直接使用现有的 requirements.txt。

Q4: 在 CI/CD 中使用？

yaml 复制代码

# GitHub Actions 示例
- name: Install uv
  uses: astral-sh/setup-uv@v3
  with:
    version: "0.6.0"

- name: Setup Python
  run: uv python install 3.12

- name: Install dependencies
  run: uv pip install -r requirements.txt

- name: Run tests
  run: uv run pytest

十、总结

uv 代表了 Python 工具链的现代化方向：

单一工具：替代 pyenv + pip + virtualenv + pip-tools 组合
极致性能：Rust 编写，安装速度提升 10-100 倍
无缝兼容：完全兼容现有 Python 生态
现代工作流：原生支持 pyproject.toml 和锁定文件

推荐迁移路径：

新项目：直接使用 uv 完整工作流
现有项目：先用 uv pip install 替代 pip install，逐步迁移