uv 完全指南

极速 Python 包管理器 - 用 Rust 重新定义 Python 开发体验

文档导航

本系列文档从多个维度深入讲解 uv，适合不同层次的 Python 开发者学习参考。

基础篇

文档	描述
uv 基础入门	uv 简介、安装配置、核心概念与快速上手
项目管理与工作流	项目初始化、依赖管理、开发工作流
虚拟环境管理	虚拟环境创建、激活、隔离与最佳实践

进阶篇

文档	描述
Python 版本管理	多版本 Python 安装、切换与项目绑定
依赖解析与锁定	依赖解析机制、锁文件详解、冲突处理
工具链与脚本执行	uvx 工具运行、脚本管理、一次性环境

高级篇

文档	描述
高级配置与性能优化	配置选项、缓存管理、性能调优
企业实践与迁移指南	从 pip/poetry 迁移、CI/CD 集成、企业最佳实践
与其他工具对比分析	与 pip、poetry、pdm、conda 等工具全面对比

---

uv 速查表

安装与更新

# 安装 uv (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 使用 pip 安装
pip install uv

# 更新 uv
uv self update

项目管理

# 创建新项目
uv init myproject                    # 创建应用项目
uv init --lib mylib                  # 创建库项目
uv init --package mypackage          # 创建可发布包

# 依赖管理
uv add requests                      # 添加依赖
uv add "requests>=2.28"              # 添加带版本约束的依赖
uv add --dev pytest                  # 添加开发依赖
uv add --optional docs sphinx        # 添加可选依赖
uv remove requests                   # 移除依赖

# 同步与锁定
uv sync                              # 同步依赖到环境
uv lock                              # 更新锁文件
uv lock --upgrade                    # 升级所有依赖
uv lock --upgrade-package requests   # 升级指定依赖

虚拟环境

# 创建虚拟环境
uv venv                              # 在 .venv 创建
uv venv myenv                        # 指定目录
uv venv --python 3.11                # 指定 Python 版本

# 激活环境 (Linux/macOS)
source .venv/bin/activate

# 激活环境 (Windows)
.venv\Scripts\activate

Python 版本管理

# 安装 Python
uv python install 3.12               # 安装指定版本
uv python install 3.11 3.12          # 安装多个版本
uv python list                       # 列出可用版本
uv python list --only-installed      # 列出已安装版本

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

包安装 (pip 兼容模式)

# 安装包
uv pip install requests              # 安装单个包
uv pip install -r requirements.txt   # 从文件安装
uv pip install -e .                  # 开发模式安装

# 其他操作
uv pip list                          # 列出已安装包
uv pip show requests                 # 显示包信息
uv pip freeze                        # 导出依赖
uv pip uninstall requests            # 卸载包

工具运行

# 运行工具 (无需安装)
uvx ruff check .                     # 运行 ruff 检查
uvx black .                          # 运行 black 格式化
uvx --from httpie http GET example.com

# 安装全局工具
uv tool install ruff
uv tool install --python 3.11 mypy
uv tool list                         # 列出已安装工具
uv tool upgrade ruff                 # 升级工具

运行项目

# 运行脚本和命令
uv run python script.py              # 运行 Python 脚本
uv run pytest                        # 运行测试
uv run -- python -m mymodule         # 运行模块

# 构建与发布
uv build                             # 构建分发包
uv publish                           # 发布到 PyPI

---

为什么选择 uv？

uv 的核心优势

1. 极致性能 - 用 Rust 编写，比 pip 快 10-100 倍
2. 统一工具链 - 集成包管理、虚拟环境、Python 版本管理
3. 现代化设计 - 支持 PEP 标准，兼容 pyproject.toml
4. 可靠的依赖解析 - 确定性解析，跨平台一致性
5. 零配置体验 - 开箱即用，智能默认配置
6. 向后兼容 - 完全兼容 pip 命令和 requirements.txt

性能对比

uv 在现代 Python 开发中的定位

• 包管理标准 - 兼容 PEP 517/518/621/660 等现代标准
• 开发效率提升 - 大幅减少依赖安装等待时间
• CI/CD 优化 - 显著加速构建流水线
• 统一开发体验 - 一个工具解决所有 Python 环境问题

---

快速开始

5 分钟上手 uv

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

# 2. 创建新项目
uv init myproject
cd myproject

# 3. 添加依赖
uv add requests flask

# 4. 运行项目
uv run python -c "import requests; print('Hello uv!')"

# 5. 开发调试
uv run pytest

从现有项目迁移

# 如果有 requirements.txt
cd existing-project
uv init
uv add $(cat requirements.txt)

# 如果有 pyproject.toml (poetry/pdm)
cd existing-project
uv sync  # uv 自动识别并同步

---

相关资源

官方资源

• uv 官方文档
• uv GitHub 仓库
• Astral 官网

社区资源

• uv Discussions
• Astral Discord
• Python Packaging User Guide

相关工具

• Ruff - 极速 Python Linter (同为 Astral 出品)
• pyproject.toml 规范
• PEP 621 - 项目元数据

---