uv

What this skill does

# uv Skill

Extremely fast Python package and project manager by Astral (Ruff creators).

## Overview

uv is a single tool that replaces:

- **pip/pip-tools** - Package installation and dependency resolution
- **virtualenv/venv** - Virtual environment creation
- **pyenv** - Python version management
- **pipx** - Tool installation and execution
- **poetry/pdm** - Project and dependency management
- **twine** - Package publishing

**Key Features:**

- 10-100x faster than pip
- Universal lockfile (`uv.lock`) for reproducible builds
- Automatic Python version management
- Built-in tool execution (`uvx`)
- PEP 723 inline script dependencies
- Drop-in pip compatibility

## Quick Reference

| Task | Command |
|------|---------|
| New project | `uv init` |
| New library | `uv init --lib` |
| Add package | `uv add <pkg>` |
| Add dev dependency | `uv add --dev <pkg>` |
| Remove package | `uv remove <pkg>` |
| Install all deps | `uv sync` |
| Install (CI/prod) | `uv sync --locked` |
| Run command | `uv run <cmd>` |
| Run tool (no install) | `uvx <tool>` |
| Install Python | `uv python install 3.12` |
| Pin Python version | `uv python pin 3.12` |
| Update all deps | `uv lock --upgrade` |
| Update one package | `uv lock --upgrade-package <pkg>` |
| Show dep tree | `uv tree` |
| Build package | `uv build` |
| Publish to PyPI | `uv publish` |

## Quick Start

### Installation

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Via pip/pipx
pipx install uv
pip install uv

# Homebrew
brew install uv
```

### Shell Completion

```bash
# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish
```

## Essential Commands

### 1. Starting a Project

```bash
# Create new project
uv init my-project          # Application (default)
uv init --lib my-library    # Library (src layout, build backend)
uv init --app my-app        # Explicit application

# Set Python version
uv python pin 3.12          # Creates .python-version

# Install Python if needed
uv python install 3.12
```

### 2. Managing Dependencies

```bash
# Add packages
uv add requests flask       # Production dependencies
uv add --dev pytest ruff    # Development dependencies
uv add --group test pytest  # Specific dependency group
uv add --optional api flask # Optional extra
uv add "httpx>=0.20"        # With version constraint

# Remove packages
uv remove requests
uv remove --dev pytest

# Update packages
uv lock --upgrade                    # All packages
uv lock --upgrade-package requests   # Single package

# View dependencies
uv tree                     # Full tree
uv tree --depth 2           # Limited depth
```

### 3. Syncing Environment

```bash
# Install all dependencies
uv sync                     # Default (includes dev)
uv sync --locked            # CI/production (strict)
uv sync --frozen            # Don't update lockfile
uv sync --no-dev            # Exclude dev dependencies
uv sync --all-extras        # Include optional extras
```

### 4. Running Code

```bash
# Run in project environment
uv run python script.py
uv run pytest
uv run flask run

# Run with temporary dependency
uv run --with pandas script.py

# Run tools without installing (uvx)
uvx ruff check .
uvx black --check .
uvx --from httpie http https://example.com
```

### 5. Python Version Management

```bash
# Install Python versions
uv python install           # Latest version
uv python install 3.12      # Specific version
uv python install 3.11 3.12 3.13  # Multiple

# List versions
uv python list
uv python list --only-installed

# Pin version
uv python pin 3.12          # Project (.python-version)
uv python pin --global 3.12 # User default

# Find Python
uv python find
uv python find ">=3.11"
```

### 6. Virtual Environments

```bash
# Create (usually automatic)
uv venv                     # Creates .venv
uv venv my-env              # Custom name
uv venv --python 3.12       # Specific Python

# Activate (optional - uv run auto-detects)
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
```

### 7. Global Tools

```bash
# Install tools globally
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install --python 3.12 mypy

# Manage tools
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff

# Setup PATH
uv tool update-shell
```

### Scripts with Inline Dependencies (PEP 723)

```bash
# Initialize script with metadata
uv init --script example.py --python 3.12

# Add dependencies to script
uv add --script example.py requests rich

# Run script (dependencies auto-installed)
uv run example.py
```

Script format:

```python
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich import print
print(requests.get("https://api.example.com").json())
```

### pip-Compatible Interface

```bash
# Install packages (requires virtual environment)
uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .         # Editable install

# Uninstall
uv pip uninstall flask

# Compile requirements
uv pip compile requirements.in -o requirements.txt

# Sync from requirements
uv pip sync requirements.txt

# Freeze environment
uv pip freeze
```

### Building and Publishing

```bash
# Build distributions
uv build                    # Creates dist/ with wheel and sdist

# Publish to PyPI
uv publish                  # Requires authentication setup

# Authenticate
uv auth login pypi          # Interactive login
uv auth login pypi --token  # API token
```

## Project Structure

```text
my-project/
├── pyproject.toml          # Project definition (required)
├── uv.lock                 # Lock file (auto-generated)
├── .venv/                  # Virtual environment (gitignored)
├── .python-version         # Python version pin (optional)
└── src/
    └── my_project/
        └── __init__.py
```

### pyproject.toml Example

```toml
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
api = ["fastapi", "uvicorn"]
dev = ["pytest", "ruff"]

[project.scripts]
my-cli = "my_project.cli:main"

[dependency-groups]
dev = ["pytest>=8", "ruff", "mypy"]
test = ["pytest-cov"]
docs = ["sphinx", "myst-parser"]

[tool.uv]
dev-dependencies = ["pytest", "ruff"]  # Alternative to dependency-groups
default-groups = ["dev"]

[tool.uv.sources]
# Git dependency
my-lib = { git = "https://github.com/user/my-lib" }
# Local path
local-pkg = { path = "./packages/local-pkg" }
# Specific index
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
```

## Configuration

### Configuration Files

**Project-level** (highest priority):

- `uv.toml` - Standalone config (preferred)
- `pyproject.toml` - Under `[tool.uv]` section

**User-level**:

- `~/.config/uv/uv.toml` (macOS/Linux)
- `%APPDATA%\uv\uv.toml` (Windows)

### Key Environment Variables

| Variable | Purpose |
|----------|---------|
| `UV_CACHE_DIR` | Cache directory location |
| `UV_PYTHON` | Default Python version |
| `UV_INDEX_URL` | Default package index |
| `UV_NO_CACHE` | Disable caching |
| `UV_FROZEN` | Use lockfile without updating |
| `UV_LOCKED` | Assert lockfile unchanged |
| `UV_COMPILE_BYTECODE` | Compile to .pyc files |
| `UV_LINK_MODE` | Package linking mode (copy, hardlink, symlink) |

## Common Workflows

### New Project Setup

```bash
# Create and enter project
uv init my-project
cd my-project

# Add dependencies
uv add flask sqlalchemy
uv add --dev pytest ruff mypy

# Run application
uv run flask run

# Run tests
uv run pytest
```

### Existing Project (from