AgentSkillsCN

uv

使用 uv 进行 Python 包与项目管理。这款极速工具可全面替代 pip、poetry、pyenv 与 virtualenv。适用于安装包、运行脚本、管理环境，或在工作空间中开展工作时使用。触发条件包括“uv”、“pip install”、“Python 项目”、“uv.lock”。

SKILL.md
--- frontmatter
name: uv
description: |
  Python package and project management with uv. Extremely fast tool replacing pip, poetry,
  pyenv, and virtualenv. Use when installing packages, running scripts, managing environments,
  or working with workspaces. Triggers: "uv", "pip install", "python project", "uv.lock".
allowed-tools: Bash, Read, Edit, Write, Grep, Glob

uv

uv is an extremely fast Python package and project manager written in Rust. It replaces pip, pip-tools, pipx, pyenv, virtualenv, and poetry.

When to Use uv

Always use uv for Python work, especially if you see:

  • •The uv.lock file
  • •uv headers in requirements* files ("This file was autogenerated by uv")

Don't use uv in projects managed by other tools:

  • •Poetry projects (poetry.lock)
  • •PDM projects (pdm.lock)

Workflows

Scripts

Use when: Running single Python files and standalone scripts.

bash
uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add inline dependencies to script

Projects

Use when: There is a pyproject.toml or uv.lock

bash
uv init                   # Create new project
uv add requests           # Add dependency
uv add --dev pytest       # Add dev dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run in project environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

Tools

Use when: Running CLI tools (ruff, pytest, mypy) without installation.

bash
uvx <tool> <args>            # Run tool without installation
uvx <tool>@<version> <args>  # Run specific version
uvx ruff check .             # Example: run ruff

Important: Only use uv tool install when explicitly requested.

Pip Interface

Use when: Legacy workflows with requirements.txt, no uv.lock present.

bash
uv venv                                # Create virtual environment
uv pip install -r requirements.txt     # Install from requirements
uv pip compile requirements.in -o requirements.txt  # Compile deps
uv pip sync requirements.txt           # Sync environment
uv pip compile --universal requirements.in -o requirements.txt  # Cross-platform

Prefer uv init for new projects over pip interface.

Workspaces

Workspaces manage multiple related packages in a monorepo structure.

Configuration

toml
# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*", "apps/*"]
exclude = ["packages/legacy"]

[tool.uv.sources]
# Local package references
mylib = { workspace = true }
shared = { path = "../shared", editable = true }

# Git sources
mypackage = { git = "https://github.com/org/repo", branch = "main" }

Structure

code
my-workspace/
├── pyproject.toml          # Root workspace config
├── uv.lock                  # Single lockfile for all packages
├── packages/
│   ├── core/
│   │   └── pyproject.toml  # [project] with dependencies
│   └── utils/
│       └── pyproject.toml
└── apps/
    └── api/
        └── pyproject.toml

Commands

bash
uv sync                           # Sync all workspace packages
uv sync --package myapp           # Sync specific package
uv run --package myapp pytest     # Run in specific package context
uv add requests --package myapp   # Add dep to specific package
uv lock                           # Update workspace lockfile

Cross-Package Dependencies

toml
# apps/api/pyproject.toml
[project]
dependencies = ["core", "utils"]

[tool.uv.sources]
core = { workspace = true }
utils = { workspace = true }

Python Version Management

bash
uv python install 3.12           # Install Python version
uv python list --only-installed  # List installed versions
uv python pin 3.12               # Pin version for project
uv python install 3.12 --default # Set as system default

Common Patterns

Don't use pip in uv projects

bash
# ❌ Bad
uv pip install requests

# ✅ Good
uv add requests

Don't run python directly

bash
# ❌ Bad
python script.py
python -c "..."

# ✅ Good
uv run script.py
uv run python -c "..."

Don't manually manage environments

bash
# ❌ Bad
python -m venv .venv
source .venv/bin/activate

# ✅ Good
uv run <command>

Running with specific Python

bash
# ❌ Bad
python3.12 -c "..."

# ✅ Good
uvx python@3.12 -c "..."
uv run -p 3.12 <command>

Migration

From pyenv

bash
pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default

From pipx

bash
pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list

From pip/pip-tools

bash
pip install package      → uv pip install package
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv

Best Practices

Project Setup:

  1. •Use uv init for new projects
  2. •Use uv add for dependencies (not pip install)
  3. •Commit uv.lock to version control
  4. •Use uv sync to reproduce environments

Workspaces:

  1. •Define members with glob patterns: packages/*
  2. •Use workspace = true for internal dependencies
  3. •Single uv.lock at root manages all packages
  4. •Run commands with --package for specific contexts

Scripts:

  1. •Use uv run script.py instead of python script.py
  2. •Use --with for ad-hoc dependencies
  3. •Use uv add --script for persistent script dependencies

Documentation