UV Project Management
UV 项目管理
Quick reference for UV project setup, dependencies, and lockfiles.
UV 项目初始化、依赖项和 lockfile 快速参考。
When to Use This Skill
何时使用此 Skill
| Use this skill when... | Use a focused sibling instead when... |
|---|
| Running , , , , or for everyday dependency management | Running a script or one-off command — use uv-run |
| Authoring or editing pyproject.toml and sections | Wiring git/path/editable deps or workspace inheritance — use uv-advanced-dependencies |
| Bootstrapping a new single-package Python project | Splitting a repo into multi-package workspaces — use uv-workspaces |
| 当你...时使用此 Skill | 改用更聚焦的配套 Skill... |
|---|
| 运行 、、、 或 进行日常依赖管理 | 运行脚本或一次性命令——使用 uv-run |
| 编写或编辑 pyproject.toml 中的 和 配置 | 配置 Git、路径、可编辑依赖项或工作区继承——使用 uv-advanced-dependencies |
| 初始化新的单包 Python 项目 | 将仓库拆分为多包工作区——使用 uv-workspaces |
When This Skill Applies
适用场景
- Initializing new Python projects ()
- Adding, removing, or updating dependencies (, )
- Managing lockfiles ()
- Syncing project environments ()
- Configuring pyproject.toml
For running scripts, see uv-run skill.
- 初始化新的 Python 项目（）
- 添加、移除或更新依赖项（、）
- 管理 lockfile（）
- 同步项目环境（）
- 配置 pyproject.toml
如需运行脚本，请参阅 uv-run Skill。
Project Initialization
项目初始化
Create new project with complete structure
Create new project with complete structure
uv init my-project
cd my-project
uv init my-project
cd my-project
Initialize in existing directory
Initialize in existing directory
Initialize with specific Python version
Initialize with specific Python version
uv init --python 3.11 my-app
uv init --python 3.11 my-app
Dependency Management
依赖管理
Add dependencies
Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add 'django>=4.0,<5.0'
uv add requests
uv add 'flask>=2.0'
uv add 'django>=4.0,<5.0'
Add development dependencies
Add development dependencies
uv add --dev pytest pytest-cov black
uv add --dev pytest pytest-cov black
Add optional dependency groups
Add optional dependency groups
uv add --group docs sphinx sphinx-rtd-theme
uv add --group docs sphinx sphinx-rtd-theme
Remove dependencies
Remove dependencies
Migrate from requirements.txt
Migrate from requirements.txt
uv add -r requirements.txt
uv add -r requirements.txt
Lockfile Operations
Lockfile 操作
Create/update lockfile (uv.lock)
Create/update lockfile (uv.lock)
Lock with upgraded packages
Lock with upgraded packages
uv lock --upgrade-package requests
uv lock --upgrade
uv lock --upgrade-package requests
uv lock --upgrade
Lock without installing (CI/CD)
Lock without installing (CI/CD)
Environment Synchronization
环境同步
Sync environment to lockfile
Sync environment to lockfile
Sync without updating lockfile
Sync without updating lockfile
Error if lockfile is out of date
Error if lockfile is out of date
UV projects follow this standard structure:
my-project/
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Locked dependency versions
├── .venv/ # Virtual environment (auto-created)
├── README.md
└── src/
└── my_project/
└── __init__.py
UV 项目采用以下标准结构：
my-project/
├── pyproject.toml # Project metadata and dependencies
├── uv.lock # Locked dependency versions
├── .venv/ # Virtual environment (auto-created)
├── README.md
└── src/
└── my_project/
└── __init__.py
Generated pyproject.toml
生成的 pyproject.toml
toml
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []
[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"
toml
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []
[build-system]
requires = ["uv_build>=0.9.2,<0.10.0"]
build-backend = "uv_build"
Starting a New Project
启动新项目
bash
uv init my-app && cd my-app
uv add ruff pytest
uv run pytest
bash
uv init my-app && cd my-app
uv add ruff pytest
uv run pytest
Adding Multiple Dependencies
添加多个依赖项
Production dependencies
Production dependencies
uv add fastapi uvicorn 'pydantic>=2.0'
uv add fastapi uvicorn 'pydantic>=2.0'
Development tooling
Development tooling
uv add --dev pytest pytest-cov ruff ty
uv add --dev pytest pytest-cov ruff ty
Documentation
Documentation
uv add --group docs sphinx mkdocs-material
uv add --group docs sphinx mkdocs-material
Updating Dependencies
更新依赖项
Update specific package
Update specific package
uv lock --upgrade-package requests
uv lock --upgrade-package requests
Update all dependencies
Update all dependencies
Sync after update
Sync after update
- Fast: 10-100x faster than pip
- Deterministic: Lockfile ensures reproducible installs
- Automatic: Creates and manages virtual environments
- Modern: Uses pyproject.toml for configuration
- Compatible: Works with pip, Poetry, and other tools
- 快速：比 pip 快 10–100 倍
- 确定性：lockfile 确保安装过程可复现
- 自动化：自动创建并管理虚拟环境
- 现代化：使用 pyproject.toml 进行配置
- 兼容：适用于 pip、Poetry 和其他工具
- uv-run - Running scripts, temporary dependencies, PEP 723
- uv-python-versions - Managing Python interpreter versions
- uv-workspaces - Monorepo and multi-package projects
- uv-advanced-dependencies - Git, path, and constraint dependencies
- uv-tool-management - Installing CLI tools globally
- python-testing - Running tests with pytest
- python-code-quality - Linting and formatting with ruff
- uv-run - 运行脚本、使用临时依赖项及 PEP 723
- uv-python-versions - 管理 Python 解释器版本
- uv-workspaces - 单体仓库和多包项目
- uv-advanced-dependencies - Git、路径和约束依赖项
- uv-tool-management - 全局安装 CLI 工具
- python-testing - 使用 pytest 运行测试
- python-code-quality - 使用 ruff 进行 lint 和格式化