uv

What this skill does

# 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

```
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 [email protected] -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

- https://docs.astral.sh/uv/llms.txt
- https://docs.astral.sh/uv/
- https://docs.astral.sh/uv/guides/projects/
- https://docs.astral.sh/uv/reference/cli/