uv 和 uvx：现代化 Python 项目管理工具
一、简介
[uv](https://docs.astral.sh/uv/) 是一个用 Rust 编写的极速 Python 包管理器和项目管理工具，由 Astral 开发。它旨在成为 pip、pip-tools、pipx、poetry、pyenv 等工具的现代化替代品，提供统一、快速、可靠的 Python 项目管理体验。
1.1 核心优势
- 极速性能：比 pip 快 10-100 倍
- 统一工具：集成多个工具的功能，一个工具解决所有问题
- 现代化设计：原生支持 PEP 标准，无需 requirements.txt
- 确定性构建：自动生成锁文件，确保环境可重现
- 跨平台支持：Windows、macOS、Linux 全平台支持
二、安装 uv
2.1 官方推荐安装方式
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
2.2 验证安装
uv --version
三、uv vs uvx：核心区别
| 工具 | 用途 | 适用场景 |
|---|---|---|
uv |
项目管理和包管理 | 开发项目、管理依赖、运行项目代码 |
uvx |
临时运行独立工具 | 运行开发工具、格式化代码、临时使用工具 |
四、uv：项目管理核心工具
4.1 项目初始化
# 创建新项目
uv init my-project
cd my-project
# 在现有目录初始化
uv init
# 指定 Python 版本
uv init --python 3.11
# 指定项目名称
uv init --name "my-awesome-project"
4.2 Python 版本管理
# 查看可用 Python 版本
uv python list
# 安装特定 Python 版本
uv python install 3.11
uv python install 3.12
# 在项目中固定 Python 版本
uv python pin 3.11
# 查找系统中的 Python
uv python find
4.3 依赖管理
4.3.1 添加依赖
# 添加生产依赖
uv add requests
uv add "django>=4.0,<5.0"
4.3.2 移除依赖
# 移除包
uv remove requests
4.3.3 查看依赖
# 查看依赖树
uv tree
4.4 环境管理
# 同步环境（安装所有依赖）
uv sync
# 重新创建环境
rm -rf .venv
uv sync
4.5 运行代码
# 运行 Python 脚本
uv run script.py
五、uvx：临时工具运行器
5.1 基本用法
# 运行代码格式化工具
uvx black .
uvx isort .
# 运行代码检查工具
uvx flake8 .
uvx pylint src/
# 运行类型检查
uvx mypy src/
5.2 常用工具清单
# 代码格式化
uvx black . # Python 代码格式化
uvx isort . # 导入语句排序
uvx autopep8 --in-place *.py # PEP8 格式化
# 代码检查
uvx flake8 . # 代码风格检查
uvx pylint src/ # 代码质量分析
uvx mypy src/ # 静态类型检查
uvx bandit -r src/ # 安全漏洞检查
# 测试工具
uvx pytest # 运行测试
uvx coverage run -m pytest # 测试覆盖率
uvx tox # 多环境测试
# 文档工具
uvx sphinx-quickstart # 初始化 Sphinx 文档
uvx mkdocs new . # 初始化 MkDocs 项目
# 项目工具
uvx cookiecutter gh:audreyr/cookiecutter-pypackage # 项目模板
uvx pre-commit install # Git 钩子工具
六、完整的项目开发流程
6.1 项目创建阶段
# 创建新项目
uv init --name "awesome-project" --python ">=3.9"
cd awesome-project
# 或使用项目模板
uvx cookiecutter gh:audreyr/cookiecutter-pypackage
cd your-project-name
uv init
6.2 依赖配置阶段
# 添加核心依赖
uv add requests fastapi
# 同步环境
uv sync
6.3 开发阶段
# 运行应用
uv run main.py
# 代码格式化
uvx black .
uvx isort .
# 代码检查
uvx flake8 .
uvx mypy src/
# 运行测试
uv run pytest
uv run pytest --cov=src tests/
6.4 代码质量保证
# 完整的代码检查流程
uvx black --check . # 检查格式
uvx isort --check-only . # 检查导入排序
uvx flake8 . # 风格检查
uvx mypy src/ # 类型检查
uvx bandit -r src/ # 安全检查
uv run pytest --cov=src # 测试和覆盖率
6.5 文档编写
# 初始化文档
uvx sphinx-quickstart docs/
# 或使用 MkDocs
uvx mkdocs new .
uvx mkdocs serve
# 生成 API 文档
uvx sphinx-apidoc -o docs/source src/
6.6 构建和发布
# 构建包
uvx build
# 检查包
uvx twine check dist/*
# 发布到 PyPI
uvx twine upload dist/*
# 发布到测试 PyPI
uvx twine upload --repository testpypi dist/*
七、pyproject.toml 配置示例
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "awesome-project"
version = "0.1.0"
description = "An awesome Python project"
readme = "README.md"
requires-python = ">=3.9"
license = {text = "MIT"}
authors = [
{name = "Your Name", email = "your.email@example.com"}
]
classifiers = [
"Development Status :: 3 - Alpha",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
]
dependencies = [
"requests>=2.28.0",
"fastapi>=0.100.0",
"pydantic>=2.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-cov>=4.1.0",
"black>=23.0.0",
"isort>=5.12.0",
"flake8>=6.0.0",
"mypy>=1.0.0",
]
db = [
"sqlalchemy>=2.0.0",
"psycopg2-binary>=2.9.0",
]
test = [
"pytest-asyncio>=0.18.0",
"factory-boy>=3.2.0",
"httpx>=0.24.0",
]
[project.scripts]
awesome-cli = "awesome_project.cli:main"
[project.urls]
Homepage = "https://github.com/username/awesome-project"
Repository = "https://github.com/username/awesome-project"
Issues = "https://github.com/username/awesome-project/issues"
[tool.black]
line-length = 88
target-version = ["py39", "py310", "py311"]
[tool.isort]
profile = "black"
line_length = 88
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = "--cov=src --cov-report=term-missing"
[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
八、常见问题和解决方案
8.1 依赖冲突
# 检查冲突
uv check
# 查看详细依赖树
uv tree --show-version-specifiers
# 强制解决冲突
uv lock --resolution-strategy highest
8.2 环境问题
# 重建环境
rm -rf .venv
uv sync
# 清理缓存
uv cache clean
# 检查 Python 安装
uv python list
8.3 性能优化
# 并行安装
uv sync --no-build-isolation
# 使用缓存
uv cache info
# 预编译包
uv add --precompiled numpy
九、最佳实践
9.1 项目结构
my-project/
├── src/
│ └── my_project/
│ ├── __init__.py
│ └── main.py
├── tests/
│ └── test_main.py
├── docs/
├── pyproject.toml
├── uv.lock
├── README.md
└── .gitignore
9.2 依赖管理
- 使用语义化版本约束：
requests>=2.28.0,<3.0.0 - 将开发依赖分组管理
- 定期更新锁文件：
uv lock --upgrade - 使用可选依赖组分离功能模块
9.3 开发工作流
# 每日开发流程
uv sync # 同步环境
uvx black . # 格式化代码
uvx isort . # 排序导入
uv run pytest # 运行测试
uvx flake8 . # 代码检查
9.4 CI/CD 集成
# GitHub Actions 示例
- name: Install uv
uses: astral-sh/setup-uv@v1
- name: Install dependencies
run: uv sync
- name: Run tests
run: uv run pytest
- name: Check code quality
run: |
uvx black --check .
uvx flake8 .
十、与其他工具对比
| 功能 | pip/venv | Poetry | uv |
|---|---|---|---|
| 安装速度 | 慢 | 中等 | 极快 |
| 依赖解析 | 基础 | 好 | 优秀 |
| 锁文件 | 手动 | 自动 | 自动 |
| Python 版本管理 | 需要 pyenv | 需要 pyenv | 内置 |
| 工具运行 | 需要 pipx | 不支持 | 内置 uvx |
| 学习曲线 | 平缓 | 中等 | 平缓 |
十一、常见命令速查表
11.1 uv 核心命令
# 项目管理
uv init # 初始化项目
uv sync # 同步依赖
uv run <command> # 运行命令
# 依赖管理
uv add <package> # 添加依赖
uv remove <package> # 移除依赖
uv tree # 查看依赖树
uv lock # 锁定依赖
# Python 版本管理
uv python list # 列出 Python 版本
uv python install <ver> # 安装 Python 版本
uv python pin <ver> # 固定项目 Python 版本
# 环境管理
uv venv # 创建虚拟环境
uv cache clean # 清理缓存
11.2 uvx 常用命令
# 代码质量工具
uvx black . # 代码格式化
uvx isort . # 导入排序
uvx flake8 . # 代码检查
uvx mypy . # 类型检查
# 开发工具
uvx jupyter lab # 启动 Jupyter Lab
uvx pytest # 运行测试
uvx sphinx-build # 构建文档
# 包管理
uvx build # 构建包
uvx twine upload # 上传包
十二、总结
uv 和 uvx 提供了现代化的 Python 项目管理解决方案：
- uv 适用于项目开发、依赖管理、环境管理
- uvx 适用于运行开发工具、临时工具使用
- 两者结合使用可以覆盖 Python 开发的全流程
- 相比传统工具，提供了更快的速度和更好的用户体验
通过本指南，您可以完全使用 uv/uvx 替代传统的 pip、venv、poetry 等工具，享受现代化 Python 开发的便利。
十三、参考资料
最后更新：2025年7月14日
