uv-workflow

# Python Development with uv

Modern Python project management using uv - the fast, Rust-powered package manager.

## When to Use This Skill

Use this skill when:
- **Creating new Python projects**
- **Managing dependencies** (adding, removing, updating)
- **Running Python scripts** in project context
- **Setting up CI/CD** for Python projects
- **Troubleshooting** virtual environment or dependency issues

## Why uv?

| Feature | uv | pip | Poetry |
|---------|-----|-----|--------|
| Speed | 10-100x faster | Baseline | 2-3x slower |
| Virtual envs | Automatic | Manual | Automatic |
| Lockfile | Cross-platform | None | Yes |
| Python version mgmt | Built-in | No | No |
| Dev dependencies | Groups | No | Yes |

## Quick Reference

### Project Setup
```bash
uv init                     # Create app project
uv init --package           # Create package (src/ layout)
uv init --lib               # Create library
```

### Dependencies
```bash
uv add requests             # Add dependency
uv add -d pytest            # Add dev dependency
uv add 'requests>=2.28'     # With version constraint
uv remove requests          # Remove dependency
uv lock --upgrade           # Update all dependencies
```

### Running Code
```bash
uv run python main.py       # Run script in project env
uv run pytest               # Run tools with dependencies
uvx ruff check .            # Run standalone tool (isolated)
```

### Environment
```bash
uv sync                     # Sync env with lockfile
uv sync --all-groups        # Include all dependency groups
uv python install 3.11      # Install Python version
uv python pin 3.11          # Pin project to version
```

## Critical Rules

### Always Use `uv run`

**Wrong** - bypasses project environment:
```bash
python main.py
pytest
```

**Correct** - uses project environment:
```bash
uv run python main.py
uv run pytest
```

### `uv run` vs `uvx`

| Command | Use For |
|---------|---------|
| `uv run pytest` | Tools that need your project code |
| `uvx ruff