Skip to main content

uv 完全指南：Python 包管理的革命性工具

🚀 什么是 uv？​

uv 是一个用 Rust 编写的极速 Python 包和项目管理器，旨在成为 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具的统一替代方案。

简单来说：uv 是 Python 的 Cargo —— 一个快速、可靠、易用的一体化解决方案。

核心特点​

  • ⚡ 极致速度：比 pip 快 10-100 倍
  • 🦀 Rust 编写：利用 Rust 的性能和内存安全特性
  • 🎯 一体化工具：替代多个工具，简化工作流
  • 🔒 依赖锁定：自动生成 uv.lock 确保环境一致性
  • 🐍 Python 版本管理：内置 Python 安装和管理
  • 💾 全局缓存：节省磁盘空间，避免重复下载
  • 📦 标准兼容：基于 pyproject.toml 标准

🏢 背后的公司：Astral​

公司背景​

uv 由 Astral 公司开发，这家公司由 Charlie Marsh 于 2022 年创立。

融资情况：

  • 💰 2023 年完成 400 万美元种子轮融资
  • 🎯 领投方：Accel（知名风投公司）
  • 🤝 参投方包括：
    • Caffeinated Capital
    • Guillermo Rauch（Vercel 创始人）
    • Solomon Hykes（Docker 创始人）
    • David Cramer（Sentry 创始人）
    • Wes McKinney（Pandas 作者）

产品线​

Astral 的开源产品生态：

  1. Ruff - 超快的 Python linter 和 formatter

    • 已被 Airflow、FastAPI、Pandas、SciPy 等采用
    • Amazon、Microsoft、Netflix、Mozilla 等公司在使用
    • 每周数百万次下载

  2. uv - 极速 Python 包管理器

    • 2024 年 2 月首次发布
    • 持续快速迭代更新

  3. Rye（已整合到 uv）- Python 项目管理工具

商业模式​

核心承诺：工具永久免费开源

  • ✅ 所有工具使用 MIT 许可证
  • ✅ 完全开源，可自由使用
  • 💼 未来计划提供企业级服务：
    • 技术支持和咨询
    • 托管服务（类似 GitHub 模式）
    • 私有包仓库
    • CI/CD 集成
    • SLA 保障

类似成功案例：

  • Vercel（Next.js 开源，托管服务收费）
  • Docker（Docker 免费，企业版收费）
  • MongoDB（数据库开源，云服务收费）

开源贡献​

Astral 建立了 OSS Fund（开源基金）：

  • 每年为每位 Astral 员工捐赠 $3,250 给开源项目
  • 每年向 Python 软件基金会捐赠 $5,000
  • 每年向 Rust 基金会捐赠 $5,000

uv 🆚 其他工具​

uv vs pip​

特性pipuv
速度基准10-100x 更快
依赖解析较慢，有时不完整快速且完整
锁定文件需要 pip-tools内置 uv.lock
缓存每个项目独立全局缓存，节省空间
Python 管理不支持✅ 内置
语言PythonRust

uv vs Poetry​

特性Poetryuv
速度中等极快
配置文件pyproject.tomlpyproject.toml
锁定文件poetry.lockuv.lock
Python 管理不支持✅ 内置
打包发布✅ 内置✅ uv build, uv publish
生态成熟度高快速增长

uv vs Conda​

特性Condauv
速度较慢极快
包来源conda-forgePyPI
非 Python 包✅ 支持（C++、CUDA 等）❌ 仅 Python
Python 管理✅ 支持✅ 支持
适用场景数据科学、复杂依赖一般 Python 开发

选择建议：

  • 纯 Python 项目 → uv
  • 需要 CUDA、C++ 等系统依赖 → Conda
  • 团队已有 Poetry 项目 → 可逐步迁移到 uv

🛠️ 主要功能​

1. 包管理（pip 替代）​

# 创建虚拟环境
uv venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# 安装包
uv pip install requests pandas numpy

# 编译依赖
uv pip compile requirements.in -o requirements.txt

# 同步依赖
uv pip sync requirements.txt

2. 项目管理（Poetry 替代）​

# 初始化项目
uv init my-project
cd my-project

# 添加依赖
uv add requests
uv add --dev pytest

# 移除依赖
uv remove requests

# 安装所有依赖
uv sync

# 运行脚本
uv run python app.py
uv run pytest

项目会自动生成：

  • pyproject.toml - 项目配置和依赖声明
  • uv.lock - 依赖锁定文件（确保可重现性）

3. Python 版本管理（pyenv 替代）​

# 安装 Python 版本
uv python install 3.11 3.12 3.13

# 列出已安装的 Python
uv python list

# 查看可用的 Python 版本
uv python list --all-versions

# 使用特定 Python 版本创建虚拟环境
uv venv --python 3.12

# 使用特定 Python 版本运行脚本
uv run --python 3.11 python script.py

注意： uv 使用 Astral 的 python-build-standalone 项目提供的预编译 Python 发行版。

4. 工具管理（pipx 替代）​

# 在临时环境中运行工具（uvx 是 uv tool run 的别名）
uvx ruff check
uvx black .
uvx pycowsay "Hello uv!"

# 全局安装工具
uv tool install ruff
uv tool install httpie

# 列出已安装的工具
uv tool list

# 卸载工具
uv tool uninstall ruff

5. 脚本依赖管理​

uv 支持 PEP 723 标准，可以在单个脚本中声明依赖：

# /// script
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

运行脚本：

uv run script.py

uv 会自动：

  1. 读取脚本中的依赖声明
  2. 创建临时虚拟环境
  3. 安装依赖
  4. 运行脚本

6. 工作区（Workspace）支持​

对于 monorepo 或多包项目：

# pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

uv 会统一管理工作区中所有包的依赖。

📦 安装 uv​

官方安装脚本（推荐）​

Linux / macOS：

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

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

包管理器安装​

# macOS (Homebrew)
brew install uv

# Python (pipx)
pipx install uv

# Python (pip) - 需要已有 Python 环境
pip install uv

# Cargo
cargo install --git https://github.com/astral-sh/uv uv

更新 uv​

# 使用官方安装脚本安装的
uv self update

# 使用 pipx 安装的
pipx upgrade uv

# 使用 pip 安装的
pip install --upgrade uv

📚 实战案例​

案例 1：从 pip 迁移到 uv​

原有项目结构：

my-project/
├── requirements.txt
├── requirements-dev.txt
└── app.py

迁移步骤：

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 创建虚拟环境
uv venv

# 3. 激活环境
source .venv/bin/activate

# 4. 安装依赖
uv pip install -r requirements.txt
uv pip install -r requirements-dev.txt

# 5. (可选) 初始化为 uv 项目
uv init --no-readme

# 6. 从 requirements.txt 添加依赖到 pyproject.toml
uv add $(cat requirements.txt | grep -v '^#' | grep -v '^$')

案例 2：创建新项目​

# 创建项目
uv init my-api
cd my-api

# 添加依赖
uv add fastapi uvicorn

# 添加开发依赖
uv add --dev pytest pytest-cov ruff

# 创建 app.py
cat > app.py << 'EOF'
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello from uv!"}
EOF

# 运行应用
uv run uvicorn app:app --reload

案例 3：管理多个 Python 版本​

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

# 为不同项目使用不同版本
cd project-a
uv venv --python 3.11
uv sync

cd ../project-b
uv venv --python 3.12
uv sync

# 测试脚本在多个 Python 版本上运行
uv run --python 3.9 pytest
uv run --python 3.10 pytest
uv run --python 3.11 pytest

案例 4：使用 uvx 运行临时工具​

# 不需要安装，直接运行工具
uvx httpie https://api.github.com
uvx black --check .
uvx ruff check src/

# 使用特定版本的工具
uvx --from 'ruff==0.1.0' ruff check

# 运行远程脚本
uvx --from 'requests' python -c "import requests; print(requests.get('https://httpbin.org/get').json())"

⚙️ 高级特性​

1. 依赖覆盖（Dependency Overrides）​

在 pyproject.toml 中强制使用特定版本：

[tool.uv]
override-dependencies = [
    "numpy==1.24.0",  # 强制所有依赖使用此版本
]

2. 约束文件（Constraints）​

# 使用约束文件限制版本范围
uv pip install -r requirements.txt -c constraints.txt

3. 平台无关的依赖解析​

# 为不同平台生成统一的锁定文件
uv pip compile requirements.in --universal -o requirements.txt

4. 源配置​

# pyproject.toml
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

5. 环境变量配置​

# 设置缓存目录
export UV_CACHE_DIR=/path/to/cache

# 禁用自动下载 Python
export UV_PYTHON_DOWNLOADS=never

# 设置 pip 源
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

🔗 官方资源​

核心链接​

文档导航​

相关项目​

学习资源​

❓ 常见问题​

Q: uv 稳定吗？可以用于生产环境吗？​

A: uv 目前处于快速发展阶段，主要 API 已经稳定。许多公司已在生产环境使用。建议：

  • ✅ 新项目可以直接使用
  • ⚠️ 重要生产项目建议先小范围试点
  • 📖 关注 release notes 和 breaking changes

Q: uv 会取代 pip 吗？​

A: uv 不是 Python 官方工具，但提供了 pip 兼容的接口。Python 核心团队还在观察社区反馈。不过：

  • uv 可以与 pip 共存
  • uv pip 命令提供 pip 兼容接口
  • 可以随时切换回 pip

Q: 如何在 CI/CD 中使用 uv？​

A: GitHub Actions 示例：

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      
      - name: Set up Python
        run: uv python install 3.12
      
      - name: Install dependencies
        run: uv sync
      
      - name: Run tests
        run: uv run pytest

Q: uv 的缓存存储在哪里？​

A:

  • Linux: ~/.cache/uv
  • macOS: ~/Library/Caches/uv
  • Windows: %LOCALAPPDATA%\uv\cache

清理缓存：uv cache clean

Q: 如何迁移现有的 Poetry 项目？​

A: Poetry 项目已经使用 pyproject.toml，迁移很简单：

# 1. 删除 Poetry 的虚拟环境
rm -rf .venv

# 2. 用 uv 创建新环境
uv venv

# 3. 安装依赖
uv sync

# 4. (可选) 删除 Poetry 配置
# 保留 pyproject.toml 中的 [tool.poetry] 不会影响 uv

Q: uv 支持私有 PyPI 源吗？​

A: 完全支持！

# 环境变量方式
export UV_INDEX_URL=https://pypi.company.com/simple

# 或在 pyproject.toml 中配置
[[tool.uv.index]]
url = "https://pypi.company.com/simple"

🎯 最佳实践​

1. 项目结构建议​

my-project/
├── .python-version      # 指定 Python 版本
├── pyproject.toml       # 项目配置和依赖
├── uv.lock              # 锁定依赖（提交到 Git）
├── .venv/               # 虚拟环境（添加到 .gitignore）
├── src/
│   └── my_project/
│       └── __init__.py
└── tests/
    └── test_main.py

2. .gitignore 配置​

# Python
__pycache__/
*.py[cod]
*$py.class

# uv
.venv/
.python-version

# 不要忽略 uv.lock！
# uv.lock 应该提交到版本控制

3. 团队协作​

推荐工作流：

# 1. 克隆项目
git clone <repo>
cd <project>

# 2. 安装 uv（如果没有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 同步依赖（uv 会自动安装 Python 和创建虚拟环境）
uv sync

# 4. 开始开发
uv run python -m my_project

4. 版本固定策略​

pyproject.toml:

[project]
dependencies = [
    "fastapi>=0.100.0,<0.101.0",  # 允许补丁版本更新
    "pydantic~=2.0.0",             # 允许兼容版本
]

uv.lock 确保完全一致的环境！

5. 定期维护​

# 检查过期的包
uv pip list --outdated

# 更新所有包到允许的最新版本
uv lock --upgrade

# 更新特定包
uv lock --upgrade-package requests

# 审计安全漏洞（需要其他工具如 pip-audit）
uvx pip-audit

🚀 未来展望​

根据 Astral 团队的路线图和社区讨论，uv 未来可能包括：

  1. ✅ 构建和发布：uv build 和 uv publish（已实现）
  2. 🔄 更好的工作区支持（持续改进中）
  3. 🔐 安全审计集成
  4. 📊 依赖可视化
  5. 🌐 更多的索引源支持
  6. 🤖 更智能的依赖解析

社区讨论：

  • 有讨论让 uv 成为 Python 官方包管理器（GitHub Issue）
  • Python 核心团队正在观察 uv 的发展

📊 采用案例​

虽然 uv 相对较新，但已有许多项目和公司开始采用：

  • 🏢 企业用户：许多科技公司在内部项目中试用
  • 📦 开源项目：越来越多的 Python 项目迁移到 uv
  • 🎓 教育机构：用于教学和研究项目
  • 🚀 初创公司：新项目首选 uv 作为包管理工具

社区反馈：

  • ⭐ GitHub 上 20,000+ stars（截至 2024 年底）
  • 📈 每周数十万次下载
  • 💬 活跃的 Discord 社区

🎓 总结​

uv 的核心价值​

  1. 速度革命：10-100x 的性能提升真实改变开发体验
  2. 简化工具链：一个工具替代多个，降低认知负担
  3. 现代化设计：学习最佳实践，标准兼容
  4. 可靠性：Rust 保证的内存安全和稳定性
  5. 开源承诺：永久免费，社区驱动

适合使用 uv 的场景​

✅ 强烈推荐：

  • 新的 Python 项目
  • 追求高效的个人开发者
  • 需要管理多个 Python 版本
  • CI/CD 流程优化

⚠️ 谨慎使用：

  • 需要非 Python 包的项目（考虑 Conda）
  • 高度依赖特定工具的旧项目
  • 团队不愿意尝试新工具