python-uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python uv

Overview

概述

uv is an extremely fast Python package and project manager written in Rust, designed to replace pip, pip-tools, pipx, poetry, pyenv, and virtualenv. It provides unified project management, dependency resolution, Python version management, and tool execution with 10-100x speed improvements over traditional tools.

Key capabilities: Project initialization, dependency locking and syncing, Python version management, PEP 723 inline script dependencies, ephemeral tool execution via

uvx

, monorepo workspaces with shared lockfiles, and package building/publishing.

When to use: Python project initialization, dependency management, virtual environments, Python version pinning, running scripts with inline dependencies, monorepo workspaces, tool execution, publishing packages.

When NOT to use: Non-Python projects, conda-managed scientific computing environments with system-level binary dependencies, projects locked to legacy

setup.py

-only workflows.

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

核心功能： 项目初始化、依赖锁定与同步、Python版本管理、PEP 723内联脚本依赖、通过

uvx

执行临时工具、支持共享锁文件的单体仓库工作区，以及包构建与发布。

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

不适用场景： 非Python项目、使用conda管理且包含系统级二进制依赖的科学计算环境、仅依赖传统

setup.py

工作流的项目。

Quick Reference

快速参考

Pattern	Command / API	Key Points
Init project	`uv init`	Creates `pyproject.toml` and `.python-version`
Init library	`uv init --lib`	Creates `src/` layout with `py.typed`
Init script	`uv init --script example.py`	PEP 723 inline metadata script
Add dependency	`uv add requests`	Adds to `pyproject.toml` , updates lockfile
Add dev dependency	`uv add --dev pytest`	Adds to `[dependency-groups]` dev group
Add group dependency	`uv add --group docs mkdocs`	Custom dependency groups
Add optional	`uv add --optional postgres psycopg`	Optional extras for libraries
Remove dependency	`uv remove requests`	Removes from `pyproject.toml` and lockfile
Lock dependencies	`uv lock`	Creates/updates `uv.lock`
Upgrade in lockfile	`uv lock --upgrade-package requests`	Targeted dependency upgrade
Sync environment	`uv sync`	Installs locked dependencies into `.venv`
Sync for CI	`uv sync --locked`	Fails if lockfile is stale
Sync frozen	`uv sync --frozen`	Skips lockfile verification
Run command	`uv run python app.py`	Runs in project virtual environment
Run script	`uv run script.py`	Supports PEP 723 inline dependencies
Run in package	`uv run --package api pytest`	Workspace-specific execution
Install Python	`uv python install 3.13`	Downloads and manages Python versions
Pin Python	`uv python pin 3.12`	Writes `.python-version` file
List Pythons	`uv python list`	Shows available and installed versions
Run tool	`uvx ruff check .`	Ephemeral tool execution
Tool with plugins	`uvx --with mkdocs-material mkdocs`	Ephemeral tool with extra packages
Install tool	`uv tool install ruff`	Persistent global tool install
Workspace	`[tool.uv.workspace]`	Monorepo multi-package support
Build package	`uv build`	Creates sdist and wheel in `dist/`
Publish	`uv publish`	Uploads to PyPI with trusted publishing
Export deps	`uv export --format requirements-txt`	Generate requirements.txt from lockfile

模式	命令/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/` 目录创建源码包和wheel包
发布包	`uv publish`	通过可信发布方式上传至PyPI
导出依赖	`uv export --format requirements-txt`	从锁文件生成requirements.txt文件

Common Mistakes

常见错误

Mistake	Correct Pattern
Using `pip install` inside uv project	`uv add` to manage via `pyproject.toml`
Activating venv manually before `uv run`	`uv run` handles venv activation automatically
Committing `.venv/` to version control	Add `.venv/` to `.gitignore` , commit `uv.lock`
Not committing `uv.lock`	Always commit `uv.lock` for reproducible builds
Using `uv sync` without `--locked` in CI	`uv sync --locked` ensures lockfile matches `pyproject.toml`
Running `uv lock --upgrade` routinely	Only upgrade intentionally, use `--upgrade-package` for targeted updates
Mixing `pip` and `uv` dependency management	Choose one tool for the project consistently
Using `uv pip install` for project deps	Use `uv add` / `uv sync` for managed projects
Forgetting `--frozen` for Docker builds	`uv sync --frozen` skips lockfile verification for faster builds
Creating venv manually in uv project	`uv sync` creates and manages `.venv` automatically
Using `setup.py` for new projects	Use `pyproject.toml` with a modern build backend
Not using `py.typed` in libraries	`uv init --lib` includes it, required for typed packages

错误操作	正确做法
在uv项目中使用 `pip install`	使用 `uv add` 通过 `pyproject.toml` 管理依赖
在执行 `uv run` 前手动激活虚拟环境	`uv run` 会自动处理虚拟环境激活
将 `.venv/` 提交至版本控制	将 `.venv/` 添加至 `.gitignore` ，提交 `uv.lock` 文件
未提交 `uv.lock` 文件	务必提交 `uv.lock` 以实现可复现的构建
在CI环境中使用 `uv sync` 时未加 `--locked` 参数	`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项目中手动创建虚拟环境	`uv sync` 会自动创建并管理 `.venv` 虚拟环境
新项目使用 `setup.py`	使用 `pyproject.toml` 搭配现代构建后端
库项目未使用 `py.typed`	`uv init --lib` 会自动包含该文件，这是类型化包的必要条件

Delegation

任务委托

Project scaffolding: Use
```
Explore
```
agent
Dependency audit: Use
```
Task
```
agent
Code review: Delegate to
```
code-reviewer
```
agent

If the
docker
skill is available, delegate containerization patterns to it. If the
github-actions
skill is available, delegate CI/CD pipeline configuration to it. If the
api-testing
skill is available, delegate API testing patterns to it. If the
sentry-setup-logging
skill is available, delegate error monitoring setup to it. If the
pino-logging
skill is available, delegate Node.js logging patterns to it (Python equivalent covered here with structlog).

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

若
docker
技能可用，将容器化模式委托给该技能处理。若
github-actions
技能可用，将CI/CD流水线配置委托给该技能处理。若
api-testing
技能可用，将API测试模式委托给该技能处理。若
sentry-setup-logging
技能可用，将错误监控设置委托给该技能处理。若
pino-logging
技能可用，将Node.js日志模式委托给该技能处理（Python等效方案在此处通过structlog覆盖）。

References

参考资料

Project management and pyproject.toml configuration
Dependency management, lockfiles, and groups
Python version management and virtual environments
Scripts, inline dependencies, and tool management
Workspace support for monorepos
FastAPI web framework patterns
Pydantic validation and data modeling
Async patterns with asyncio
Type checking with mypy and pyright
Testing with pytest
Logging with structlog
CLI applications with typer
Docker integration and publishing

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