astral-uv

astral-uv follows the SKILL.md standard. Use the install command to add it to your agent stack.

---
name: astral-uv
description: >
  Fast Python package and project management using Astral's uv. Use when
  installing packages, managing virtual environments, running Python scripts,
  or initializing Python projects. Triggers on: pyproject.toml, requirements.txt,
  Python dependency discussions, virtual environment setup.
license: MIT
metadata:
  author: Ian
  version: "1.0"
---

# Astral UV

UV is an extremely fast Python package installer and resolver written in Rust.

## Quick Reference

| Task | Command |
|------|---------|
| Create venv | `uv venv` |
| Install package | `uv pip install <pkg>` |
| Add dependency | `uv add <pkg>` |
| Run script | `uv run <script.py>` |
| Sync dependencies | `uv sync` |
| Init project | `uv init` |

## Project Management

Initialize a new project:
```bash
uv init my-project
cd my-project
```

Add dependencies (updates pyproject.toml automatically):
```bash
uv add requests httpx
uv add --dev pytest ruff
```

Sync environment with lockfile:
```bash
uv sync
```

## Running Code

Run scripts without manual venv activation:
```bash
uv run python script.py
uv run pytest
uv run ruff check .
```

Run with inline dependencies:
```bash
uv run --with requests script.py
```

## Virtual Environments

```bash
uv venv                    # Create .venv
uv venv --python 3.12      # Specific Python version
```

## pip Interface

Drop-in pip replacement (10-100x faster):
```bash
uv pip install requests
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
```

## Python Version Management

```bash
uv python install 3.12     # Install Python version
uv python list             # Show available versions
uv python pin 3.12         # Pin version for project
```

## Best Practices

1. Prefer `uv add` over `uv pip install` for project dependencies
2. Use `uv run` instead of activating venvs manually
3. Commit `uv.lock` to version control
4. Use `uv sync --frozen` in CI for reproducible builds
5. Add dev dependencies with `uv add --dev`