python-uv

Python uv

概述

uv 是一款使用 Rust 编写的超高速 Python 包和项目管理器，旨在替代 pip、pip-tools、pipx、poetry、pyenv 和 virtualenv。它提供统一的项目管理、依赖解析、Python 版本管理和工具执行功能，速度比传统工具快 10–100 倍。

主要功能： 项目初始化、依赖锁定与同步、Python 版本管理、PEP 723 内联脚本依赖、通过 uvx 临时执行工具、使用共享锁文件的单体仓库工作区，以及包的构建与发布。

适用场景： Python 项目初始化、依赖管理、虚拟环境、固定 Python 版本、运行带内联依赖的脚本、单体仓库工作区、工具执行、发布包。

不适用场景： 非 Python 项目、依赖系统级二进制文件且由 conda 管理的科学计算环境、仅使用旧版 setup.py 工作流的项目。

快速参考

模式	命令 / API	要点
初始化项目	uv init	创建 pyproject.toml 和 .python-version
初始化库	uv init --lib	创建包含 py.typed 的 src/ 布局
初始化脚本	uv init --script example.py	PEP 723 内联元数据脚本
添加依赖	uv add requests	添加到 pyproject.toml，并更新锁文件
添加开发依赖	uv add --dev pytest	添加到 [dependency-groups] 的 dev 组
添加组依赖	uv add --group docs mkdocs	自定义依赖组
添加可选依赖	uv add --optional postgres psycopg	库的可选额外依赖
移除依赖	uv remove requests	从 pyproject.toml 和锁文件中移除
锁定依赖	uv lock	创建或更新 uv.lock
升级锁文件中的依赖	uv lock --upgrade-package requests	定向升级依赖
同步环境	uv sync	将锁定的依赖安装到 .venv
为 CI 同步	uv sync --locked	如果锁文件已过期则失败
冻结模式同步	uv sync --frozen	跳过锁文件验证
运行命令	uv run python app.py	在项目虚拟环境中运行
运行脚本	uv run script.py	支持 PEP 723 内联依赖
在包中运行	uv run --package api pytest	工作区专属执行
安装 Python	uv python install 3.13	下载并管理 Python 版本
固定 Python 版本	uv python pin 3.12	写入 .python-version 文件
列出 Python 版本	uv python list	显示可用和已安装的版本
运行工具	uvx ruff check .	临时运行工具
使用插件运行工具	uvx --with mkdocs-material mkdocs	临时运行带额外软件包的工具
安装工具	uv tool install ruff	持久安装全局工具
工作区	[tool.uv.workspace]	支持多包单体仓库
构建包	uv build	在 dist/ 中创建 sdist 和 wheel
发布	uv publish	使用可信发布上传到 PyPI
导出依赖	uv export --format requirements-txt	根据锁文件生成 requirements.txt

常见错误

错误	正确做法
在 uv 项目中使用 pip install	使用 uv add 通过 pyproject.toml 管理
在运行 uv run 前手动激活 venv	uv run 会自动处理 venv 激活
将 .venv/ 提交到版本控制	将 .venv/ 添加到 .gitignore，并提交 uv.lock
不提交 uv.lock	始终提交 uv.lock，以确保构建可复现
在 CI 中使用不带 --locked 的 uv sync	使用 uv sync --locked 确保锁文件与 pyproject.toml 一致
例行运行 uv lock --upgrade	仅在有意升级时使用；针对性更新请使用 --upgrade-package
混用 pip 和 uv 管理依赖	在整个项目中始终选择一种工具
使用 uv pip install 安装项目依赖	对受管理的项目使用 uv add/uv sync
Docker 构建时忘记使用 --frozen	使用 uv sync --frozen 跳过锁文件验证，以加快构建
在 uv 项目中手动创建 venv	uv sync 会自动创建并管理 .venv
为新项目使用 setup.py	使用带有现代构建后端的 pyproject.toml
库中未使用 py.typed	uv init --lib 会包含该文件；类型化包必须使用它

任务委派

• 项目脚手架搭建：使用 Explore Agent
• 依赖审计：使用 Task Agent
• 代码审查：委派给 code-reviewer Agent

如果有 docker skill，请将容器化模式委派给它。 如果有 github-actions skill，请将 CI/CD 流水线配置委派给它。 如果有 api-testing skill，请将 API 测试模式委派给它。 如果有 sentry-setup-logging skill，请将错误监控设置委派给它。 如果有 pino-logging skill，请将 Node.js 日志记录模式委派给它（本文介绍了 Python 对应方案 structlog）。

参考资料

• 项目管理和 pyproject.toml 配置
• 依赖管理、锁文件和分组
• Python 版本管理和虚拟环境
• 脚本、内联依赖和工具管理
• 单体仓库的工作区支持
• FastAPI Web 框架模式
• Pydantic 验证和数据建模
• 使用 asyncio 的异步模式
• 使用 mypy 和 pyright 进行类型检查
• 使用 pytest 进行测试
• 使用 structlog 进行日志记录
• 使用 typer 构建 CLI 应用
• Docker 集成和发布