uv-project-management

UV 项目管理

UV 项目设置、依赖项和锁文件的快速参考。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用专门的关联技能……
使用 uv init、uv add、uv remove、uv lock 或 uv sync 进行日常依赖项管理	运行脚本或一次性命令——使用 uv-run
编写或编辑 pyproject.toml 的 [project] 和 [tool.uv] 部分	配置 git/path/editable 依赖项或工作区继承——使用 uv-advanced-dependencies
为单包 Python 项目搭建基础结构	将仓库拆分为多包工作区——使用 uv-workspaces

此技能的适用场景

• 初始化新的 Python 项目（uv init）
• 添加、移除或更新依赖项（uv add、uv remove）
• 管理锁文件（uv lock）
• 同步项目环境（uv sync）
• 配置 pyproject.toml

如需运行脚本，请参阅 uv-run 技能。

快速参考

项目初始化

# Create new project with complete structure
uv init my-project
cd my-project

# Initialize in existing directory
uv init

# Initialize with specific Python version
uv init --python 3.11 my-app

依赖项管理

# Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add 'django>=4.0,<5.0'

# Add development dependencies
uv add --dev pytest pytest-cov black

# Add optional dependency groups
uv add --group docs sphinx sphinx-rtd-theme

# Remove dependencies
uv remove requests flask

# Migrate from requirements.txt
uv add -r requirements.txt

锁文件操作

# Create/update lockfile (uv.lock)
uv lock

# Lock with upgraded packages
uv lock --upgrade-package requests
uv lock --upgrade

# Lock without installing (CI/CD)
uv lock --frozen

环境同步

# Sync environment to lockfile
uv sync

# Sync without updating lockfile
uv sync --frozen

# Error if lockfile is out of date
uv sync --locked

项目结构

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

生成的 pyproject.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"

常见工作流

开始新项目

uv init my-app && cd my-app
uv add ruff pytest
uv run pytest

添加多个依赖项

# Production dependencies
uv add fastapi uvicorn 'pydantic>=2.0'

# Development tooling
uv add --dev pytest pytest-cov ruff ty

# Documentation
uv add --group docs sphinx mkdocs-material

更新依赖项

# Update specific package
uv lock --upgrade-package requests

# Update all dependencies
uv lock --upgrade

# Sync after update
uv sync

主要特性

• 快速：速度比 pip 快 10–100 倍
• 确定性：锁文件可确保安装可重复
• 自动化：创建并管理虚拟环境
• 现代化：使用 pyproject.toml 进行配置
• 兼容：可与 pip、Poetry 和其他工具配合使用

另请参阅

• 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 进行代码检查和格式化

参考资料

• 官方文档：https://docs.astral.sh/uv/
• GitHub：https://github.com/astral-sh/uv
• 详细指南：请参阅此技能目录中的 REFERENCE.md