---
name: "uv (Python Package Manager)"
description: "Skill for uv (Python Package Manager) — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["uv-python", "dev", "auto-generated"]
---

# uv (Python Package Manager)

---
name: uv (Python Package Manager)
description: Use when managing Python projects, dependencies, virtual environments, or need faster pip/poetry alternatives. Ideal for Python development workflows requiring speed and modern dependency resolution.
category: dev
metadata:
  author: skynet
  version: 1.0.0
---

# uv - Ultrafast Python Package Manager

## Core Commands

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

# Initialize in existing directory
uv init --app  # Create application structure
uv init --lib  # Create library structure

# Add dependencies
uv add requests
uv add "fastapi[all]>=0.68.0"
uv add --dev pytest black
uv add --optional docs sphinx

# Remove dependencies
uv remove requests
uv remove --dev pytest
```

### Virtual Environment Management
```bash
# Create virtual environment
uv venv
uv venv .venv --python 3.11
uv venv --seed  # Include pip, setuptools, wheel

# Activate environment
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Install dependencies
uv pip install -r requirements.txt
uv pip install --editable .
```

### Package Installation
```bash
# Install packages (pip replacement)
uv pip install package-name
uv pip install "package>=1.0,<2.0"
uv pip install -e git+https://github.com/user/repo.git

# Install from requirements
uv pip install -r requirements.txt --upgrade
uv pip install -r requirements-dev.txt --no-deps

# Generate requirements
uv pip freeze > requirements.txt
uv pip compile requirements.in  # Generate .txt from .in
```

## Lock File Management

```bash
# Generate lock file
uv lock

# Install from lock file
uv sync
uv sync --dev  # Include dev dependencies
uv sync --no-dev  # Exclude dev dependencies

# Update dependencies
uv lock --upgrade
uv lock --upgrade-package requests
```

## Running Commands

```bash
# Run scripts in project environment
uv run python script.py
uv run pytest
uv run --with requests -- python -c "import requests; print('OK')"

# Run with specific Python version
uv run --python 3.11 script.py

# Run tools without installing
uv tool run black .
uv tool run --from flask flask run
```

## Decision Trees

### Choosing Installation Method
```
New Python project?
├── Yes → uv init → uv add dependencies
└── No → Existing project?
    ├── Has pyproject.toml → uv sync
    ├── Has requirements.txt → uv pip install -r requirements.txt
    └── Legacy setup → uv venv → uv pip install
```

### Dependency Management Strategy
```
Project type?
├── Application → uv lock (commit lock file)
├── Library → uv add (no lock file in repo)
└── Monorepo → uv workspace for multi-package setup
```

## Common Workflows

### New Project Setup
```bash
# Complete new project workflow
uv init --app my-api
cd my-api
uv add fastapi uvicorn
uv add --dev pytest black isort
uv run uvicorn main:app --reload
```

### Migrating from pip/poetry
```bash
# From pip
uv venv
uv pip install -r requirements.txt
uv pip freeze > uv-requirements.txt

# From poetry
uv init
# Copy dependencies from pyproject.toml manually or:
uv add $(poetry show --only=main --no-dev | awk '{print $1}')
```

### CI/CD Pipeline
```bash
# In CI/CD (GitHub Actions, etc.)
uv sync --frozen  # Fail if lock file is outdated
uv run pytest
uv run black --check .
```

## Advanced Features

### Workspaces (Monorepo)
```toml
# pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]
```

```bash
uv add --package package-a requests
uv sync --package package-b
```

### Tool Management
```bash
# Install tools globally
uv tool install black
uv tool install --python 3.11 mypy

# List installed tools
uv tool list

# Upgrade tools
uv tool upgrade black
uv tool upgrade-all
```

### Python Version Management
```bash
# Install Python versions
uv python install 3.11 3.12
uv python list

# Pin Python version
echo "3.11" > .python-version
uv venv  # Uses pinned version
```

## Configuration

### pyproject.toml
```toml
[tool.uv]
dev-dependencies = [
    "pytest>=7.0",
    "black",
    "isort"
]

[tool.uv.sources]
my-package = { git = "https://github.com/user/repo.git" }
local-package = { path = "../local-pkg", editable = true }
```

### Environment Variables
```bash
export UV_INDEX_URL="https://pypi.org/simple"
export UV_EXTRA_INDEX_URL="https://my-private-index.com"
export UV_NO_CACHE=1
export UV_CACHE_DIR="/custom/cache"
```

## Troubleshooting

### Common Errors

**"No solution found when resolving dependencies"**
```bash
# Check for conflicting requirements
uv add --resolution=lowest-direct package-name
# Or relax constraints
uv add "package-name>=1.0" --upgrade
```

**"Failed to download package"**
```bash
# Clear cache and retry
uv cache clean
uv pip install package-name --refresh

# Use different index
uv pip install --index-url https://pypi.org/simple package-name
```

**"Permission denied" on Windows**
```bash
# Run as administrator or use user install
uv pip install --user package-name
# Or check antivirus blocking
```

**Lock file out of sync**
```bash
# Regenerate lock file
uv lock --upgrade
# Or force sync
uv sync --refresh
```

### Performance Issues
```bash
# Parallel installation
uv pip install -r requirements.txt --compile

# Skip dependency resolution
uv pip install package-name --no-deps

# Use local cache
export UV_CACHE_DIR="/fast/ssd/cache"
```

### Debug Mode
```bash
# Verbose output
uv -v pip install package-name
uv -vv sync  # Extra verbose

# Dry run
uv add --dry-run package-name
```

## Migration Helpers

### From pip-tools
```bash
# Replace pip-compile
uv pip compile requirements.in -o requirements.txt

# Replace pip-sync
uv pip sync requirements.txt
```

### From Poetry
```bash
# Export poetry deps
poetry export -f requirements.txt --output requirements.txt
uv pip install -r requirements.txt

# Convert pyproject.toml manually for uv format
```

## Performance Benefits

- **10-100x faster** than pip for resolution
- **Parallel downloads** and installations  
- **Global cache** shared across projects
- **Incremental resolution** for updates
- **Memory efficient** dependency resolution

Use `uv` as drop-in replacement for pip with significant speed improvements and modern Python project management features.