UV是新一代Python包和项目管理工具。它使用Rust语言编写，具有非凡的性能和全面的功能。强烈推荐给全部Python开发者。
中文文档：https://uv.doczh.com/
一、为什么选择UV
- 「统一工具链」：一个工具替代pip、pip-tools、pipx、poetry、pyenv、virtualenv等
- 「全面的项目管理」：支持依赖管理、智能依赖解析、环境隔离、锁文件
- 「Python版本管理」：安装和管理不同版本的Python
- 「工具运行和安装」：可以直接运行和安装Python应用
- 「兼容pip」：提供pip兼容接口，无需改变现有工作流
二、快速上手
Step 1️⃣：一键安装
首先，您需要通过以下命令安装UV。根据您的操作系统，选择对应的安装方式。
# macOS/Linux 用户
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows 用户
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 也可以用包管理器
brew install uv # macOS
scoop install uv # Windows
Step 2️⃣：创建项目
安装完成后，使用 uv init 命令来初始化一个新的项目。这会创建一个标准的项目结构，包含所有必要的配置文件。
uv init mcp-server-db
cd mcp-server-db
# 自动生成标准项目结构 📁
# ├── README.md
# ├── pyproject.toml
# ├── .gitignore
# ├── .python-version
# └── main.py
.python-version：Python版本信息
Step 3️⃣：管理依赖
项目创建后，您可以使用 uv add 添加项目依赖，使用 uv sync 安装所有依赖，并使用 uv run 在项目的虚拟环境中运行脚本。
# 添加包，类似pip install
uv add requests mpc[lic]
# 添加开发工具
uv add pytest black ruff --dev
# 一键安装所有依赖
uv sync
# 运行代码（自动激活环境）
uv run python main.py
三、日常使用技巧
🛠️ 项目管理篇
快速添加依赖
uv add 命令功能强大，不仅可以添加依赖，还能指定版本、分组管理和标记可选依赖。
# 基础用法
uv add requests # 添加最新版本
uv add "django>=4.0" # 指定版本范围
uv add pytest --dev # 开发依赖
# 同时也支持pip命令
uv pip install -r requirements.txt
# 高级用法
uv add jupyter --group notebook # 分组管理
uv add mysql-connector-python --optional database # 可选依赖
环境同步
uv sync 命令根据
pyproject.toml 和 uv.lock 文件来同步您的项目环境，确保依赖完全一致。
# 完整同步（包括开发依赖）
uv sync
# 只要生产依赖
uv sync --no-dev
# 同步特定组
uv sync --group docs --group test
🐍 Python版本管理篇
UV内置了Python版本管理功能，可以轻松安装、切换和使用不同版本的Python解释器。
# 查看可用版本
uv python list
# 安装多个Python版本
uv python install 3.10 3.11 3.12
# 为项目指定Python版本
uv python pin 3.11
# 用不同版本测试
uv run --python 3.10 pytest
uv run --python 3.12 pytest
🔧 工具安装与运行篇
全局工具安装
UV可以像 pipx 一样全局安装Python命令行工具，每个工具都有独立的隔离环境，不会污染系统Python。
# 安装全局工具
uv tool install black ruff jupyter
uv tool install black==23.12.0
uv tool install "ruff>=0.1.0,<0.2.0"
# 管理已安装工具
uv tool list
uv tool upgrade black
uv tool uninstall jupyter
使用 uvx：一键运行无需安装
uvx 是UV最强大的特性之一。它允许您直接运行任何Python工具，无需预先安装。UV会在后台自动创建一个临时隔离环境，安装并运行工具，然后清理环境。这类似于 npx 在JavaScript生态中的作用。
# 直接运行工具（无需安装）
uvx black . # 格式化当前目录
uvx ruff check . # 运行代码检查
uvx pytest # 运行测试
uvx python -m http.server 8080 # 运行Python模块
# 一次性运行特定版本的工具
uvx "black==23.12.0" .
uvx "ruff@0.1.6" check .
# 运行GitHub仓库中的脚本
uvx "git+https://github.com/astral-sh/ruff" check .
「uvx的典型使用场景：」
「uvx vs uv tool run：」
uvx 更简洁，是 uv tool run 的快捷方式uv tool run 需要工具已通过 uv tool install 安装
实战操作
🆕 新项目快速启动
这是一条从零开始创建并配置一个Python项目的完整命令流。
# 1. 创建项目
uv init web-scraper
cd web-scraper
# 2. 添加依赖
uv add requests beautifulsoup4 pandas
# 3. 添加开发工具
uv add pytest black ruff --dev
# 4. 开始编码
uv run python main.py
👥 团队协作
在团队协作中，UV的锁文件(uv.lock)能确保所有成员拥有完全一致的依赖环境。
# 队友拉取代码后一键安装
git clone project-repo
cd project-repo
uv sync # 根据uv.lock完全复现环境
# 更新依赖后通知队友
uv add new-package
git add uv.lock pyproject.toml
git commit -m "Add new-package dependency"
🚢 部署准备
UV提供命令帮助您将项目导出为传统格式、构建分发包或发布到PyPI。
# 生成requirements.txt给Docker用
uv export --format requirements-txt > requirements.txt
# 构建发布包
uv build
# 发布到PyPI
uv publish
从其他工具迁移
从pip + venv迁移
如果您有一个使用 requirements.txt 的传统项目，迁移到UV非常容易。
# 有requirements.txt的项目
uv init
uv add -r requirements.txt
# 完成！🎉
从Poetry迁移
UV的设计兼容 pyproject.toml，因此从Poetry迁移通常无需任何额外操作。
# Poetry项目直接兼容
uv sync # 自动识别pyproject.toml
# 就这么简单！✨
从Pipenv迁移
从Pipenv迁移需要先导出依赖列表，然后用UV重新安装。
# 导出现有依赖
pipenv requirements > requirements.txt
uv init
uv add -r requirements.txt
rm Pipfile Pipfile.lock # 清理旧文件
🆘 遇到问题？秒速解决！
常见问题速查
以下是一些常用的诊断和修复命令，可以帮助您快速解决常见问题。
# 清理缓存
uv cache clean
# 重建环境
rm -rf .venv && uv sync
# 查看依赖树
uv tree
# 详细日志调试
uv sync --verbose
# 检查配置
uv --version
救命技巧
当遇到依赖冲突或环境不一致的棘手问题时，可以尝试以下命令进行高级修复。
# 依赖冲突解决
uv lock --resolution lowest-direct
# 验证环境一致性
uv lock --check
# 强制重新解析
uv lock --upgrade
UV 是新一代 Python 项目管理工具，用 Rust 编写，速度极快。实现了包管理、依赖管理、项目管理、工具管理、团队协作、python版本管理的一个全面的工具链，能 10-100 倍加速依赖安装。大幅提升 Python 开发体验和效率。
