uv-package-manager

UV 包管理器技能

何时启用

在以下情况下启用此技能：

• 创建新的 Python 项目
• 添加或移除依赖项
• 运行 Python 脚本或工具
• 管理虚拟环境
• 设置 Python 版本管理

为什么选择 UV？

• 速度比 pip 快 10–100 倍（Rust 实现）
• 统一工具——取代 pip、pip-tools、poetry、pyenv、virtualenv
• 可靠——使用锁定文件实现可复现构建
• 现代化——专为当前 Python 工作流打造

快速命令

# Project Management
uv init                      # Create new project
uv init --package my-lib     # Create installable package

# Dependencies
uv add requests              # Add dependency
uv add --dev pytest          # Add dev dependency
uv remove package-name       # Remove dependency

# Running Code
uv run script.py             # Run Python script
uv run pytest                # Run installed tool
uv run python -m module      # Run module

# Environment
uv sync                      # Sync dependencies
uv sync --frozen             # Sync without updating lock
uv lock                      # Update lock file
uv python install 3.12       # Install Python version

创建项目

# Standard project
uv init my-project
cd my-project

# Package project (for libraries)
uv init --package my-library

# Specify Python version
uv init --python 3.11

创建的结构

my-project/
├── .python-version    # Python version
├── pyproject.toml     # Project config
├── .venv/             # Virtual environment (auto-created)
└── hello.py           # Sample script

添加依赖项

# Basic add
uv add requests fastapi uvicorn

# With version constraints
uv add "django>=4.2,<5.0"
uv add "requests==2.31.0"
uv add "fastapi[all]"

# Dev dependencies
uv add --dev pytest black ruff mypy

# From git
uv add --git https://github.com/user/repo --branch develop

运行脚本

# Run Python script
uv run script.py

# Run with arguments
uv run script.py --input data.csv

# Run dev tools
uv run pytest tests/ -v
uv run black .
uv run ruff check .

# Run with temporary dependency
uv run --with httpx fetch_data.py

# Start Python REPL
uv run python

虚拟环境

UV 会自动管理虚拟环境：

# Created automatically on first use
uv sync          # First sync
uv add package   # First package add
uv run script.py # First run

# Manual creation
uv venv
uv venv --python 3.11

# Manual activation (rarely needed)
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

锁定文件

# Generate/update lock file
uv lock

# Sync from lock (normal)
uv sync

# Sync without updating (CI/CD)
uv sync --frozen

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

# ALWAYS commit these files:
# - pyproject.toml
# - uv.lock
# - .python-version

Python 版本管理

# List available versions
uv python list

# Install specific version
uv python install 3.12

# Set project version
echo "3.12" > .python-version

从 pip 迁移

# Import requirements.txt
uv init my-project
cd my-project
uv add -r requirements.txt

# Import dev requirements
uv add --dev -r requirements-dev.txt

常见的 pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.20.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
]

最佳实践

应该 ✅

• 提交 uv.lock 和 .python-version
• 为依赖项使用语义化版本
• 使用 --dev 添加开发工具
• 使用 uv run，而不是手动激活
• 在 CI/CD 中使用 --frozen

不应该 ❌

• 提交 .venv/ 目录
• 使用 * 作为版本约束
• 在同一项目中混用 pip 和 uv
• 更改后跳过锁定文件更新

故障排除

# Clear cache
uv cache clean

# Verbose mode for debugging
uv --verbose add package

# Regenerate lock
uv lock
uv sync

相关资源

请参阅 AgentUsage/uv_usage.md，获取完整文档，包括：

• Docker 集成模式
• 对 monorepo 的工作区支持
• CI/CD 配置
• 详细的迁移指南