python-uv skill

---
name: python-uv
description: Manage Python with uv instead of pip/virtualenv. Use when running Python scripts, installing packages, or creating virtual environments.
version: 1.0.0
---

# Python uv

## Overview

Expert guidance for using **uv** - the extremely fast Python package and project manager by Astral. Written in Rust, 10-100x faster than pip. Replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv.

## Instructions

### 1. New Project Setup

```bash
# Create new project
uv init my-project
cd my-project

# Or initialize in current directory
uv init
```

Creates standard structure:
```
my-project/
├── .python-version
├── .gitignore
├── pyproject.toml
├── README.md
└── main.py
```

### 2. Dependency Management

```bash
# Add dependencies
uv add requests
uv add 'flask>=2.0'
uv add httpx aiofiles          # Multiple packages

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

# Add optional dependencies
uv add --optional gui pyqt6

# Remove dependencies
uv remove requests

# Sync environment with lockfile
uv sync

# Update lockfile
uv lock
uv lock --upgrade-package flask  # Upgrade specific
```

### 3. Running Code

```bash
# Run script (auto-syncs environment)
uv run main.py

# Run command in project environment
uv run pytest
uv run ruff check .

# Run with env file
uv run --env-file .env main.py

# Run with extra dependencies (not installed)
uv run --with rich main.py
```

**Key insight:** Use `uv run` instead of activating venv. It's faster and ensures sync.

### 4. Python Version Management

```bash
# Install latest Python
uv python install

# Install specific version
uv python install 3.12
uv python install 3.11 3.12    # Multiple versions

# Set as default (creates python/python3 symlinks)
uv python install --default

# List installed versions
uv python list

# Pin project to specific version
uv python pin 3.12
```

### 5. Tool Management (replaces pipx)

```bash
# Run tool without installing
uvx ruff check .
uvx black --check .

# Install tool globally
uv tool install ruff
uv tool install 'httpie>=3.0'

# Upgrade tool
uv tool upgrade ruff

# List installed tools
uv tool list
```

### 6. pip Interface (for compatibility)

```bash
# Install packages
uv pip install flask
uv pip install -r requirements.txt

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

# Show installed packages
uv pip list
uv pip show flask
```

## Examples

### Example: Create FastAPI Project

**Input:** "Create a new FastAPI project with testing"

```bash
uv init fastapi-app
cd fastapi-app
uv add fastapi uvicorn
uv add --dev pytest httpx pytest-asyncio
```

```python
# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}
```

```bash
# Run development server
uv run uvicorn main:app --reload

# Run tests
uv run pytest
```

### Example: Migrate from requirements.txt

**Input:** "Migrate existing project to uv"

```bash
# In project directory
uv init

# Import existing dependencies
uv add -r requirements.txt

# Remove old requirements.txt (optional)
rm requirements.txt

# Now use uv.lock for reproducibility
git add uv.lock pyproject.toml
```

### Example: Run One-off Script

**Input:** "Run a script with dependencies not in project"

```bash
# Run with temporary dependencies
uv run --with pandas --with matplotlib script.py

# Or use inline metadata (PEP 723)
```

```python
# /// script
# dependencies = ["pandas", "matplotlib"]
# ///

import pandas as pd
import matplotlib.pyplot as plt
# ...
```

```bash
uv run script.py  # Auto-installs inline deps
```

### Example: CI/CD Setup

**Input:** "Setup GitHub Actions with uv"

```yaml
# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Set up Python
        run: uv python install

      - name: Install dependencies
        run: uv sync --locked --all-extras --dev

      - name: Run tests
        run: uv run pytest

      - name: Run linter
        run: uv run ruff check .
```

### Example: Docker Production

**Input:** "Create Dockerfile with uv"

```dockerfile
FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# Set environment for production
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=copy

WORKDIR /app

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies (no dev, locked versions)
RUN uv sync --locked --no-dev --no-install-project

# Copy application
COPY . .

# Install project
RUN uv sync --locked --no-dev

CMD ["uv", "run", "python", "-m", "myapp"]
```

## Quick Reference

| Task | Command |
|------|---------|
| New project | `uv init` |
| Add package | `uv add <pkg>` |
| Add dev dep | `uv add --dev <pkg>` |
| Remove package | `uv remove <pkg>` |
| Sync env | `uv sync` |
| Run script | `uv run <script.py>` |
| Run command | `uv run <cmd>` |
| Install Python | `uv python install 3.12` |
| Run tool (no install) | `uvx <tool>` |
| Install tool | `uv tool install <tool>` |

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `UV_COMPILE_BYTECODE=1` | Compile .pyc (faster startup) |
| `UV_NO_SYNC=1` | Skip sync in `uv run` |
| `UV_LINK_MODE=copy` | Copy files instead of hardlink |
| `UV_MANAGED_PYTHON=1` | Only use uv-managed Python |

## Guidelines

### Do

- Use `uv run` instead of activating venv
- Commit `uv.lock` for reproducible builds
- Use `--locked` in CI/CD
- Use `--dev` for test/lint dependencies
- Use `uvx` for one-off tool usage

### Don't

- Activate venv manually (use `uv run`)
- Forget to commit `uv.lock`
- Mix pip and uv in same project
- Skip `--locked` in production

## Migration Cheatsheet

| Old Tool | uv Equivalent |
|----------|---------------|
| `pip install X` | `uv add X` or `uv pip install X` |
| `pip install -r requirements.txt` | `uv add -r requirements.txt` |
| `python script.py` | `uv run script.py` |
| `pipx run ruff` | `uvx ruff` |
| `pipx install ruff` | `uv tool install ruff` |
| `pyenv install 3.12` | `uv python install 3.12` |
| `poetry add X` | `uv add X` |
| `poetry install` | `uv sync` |
| `poetry lock` | `uv lock` |