Uv Package Manager

1---2name: uv-package-manager3description: Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.4---5 6# UV Package Manager7 8Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.9 10## When to Use This Skill11 12- Setting up new Python projects quickly13- Managing Python dependencies faster than pip14- Creating and managing virtual environments15- Installing Python interpreters16- Resolving dependency conflicts efficiently17- Migrating from pip/pip-tools/poetry18- Speeding up CI/CD pipelines19- Managing monorepo Python projects20- Working with lockfiles for reproducible builds21- Optimizing Docker builds with Python dependencies22 23## Core Concepts24 25### 1. What is uv?26 27- **Ultra-fast package installer**: 10-100x faster than pip28- **Written in Rust**: Leverages Rust's performance29- **Drop-in pip replacement**: Compatible with pip workflows30- **Virtual environment manager**: Create and manage venvs31- **Python installer**: Download and manage Python versions32- **Resolver**: Advanced dependency resolution33- **Lockfile support**: Reproducible installations34 35### 2. Key Features36 37- Blazing fast installation speeds38- Disk space efficient with global cache39- Compatible with pip, pip-tools, poetry40- Comprehensive dependency resolution41- Cross-platform support (Linux, macOS, Windows)42- No Python required for installation43- Built-in virtual environment support44 45### 3. UV vs Traditional Tools46 47- **vs pip**: 10-100x faster, better resolver48- **vs pip-tools**: Faster, simpler, better UX49- **vs poetry**: Faster, less opinionated, lighter50- **vs conda**: Faster, Python-focused51 52## Installation53 54### Quick Install55 56```bash57# macOS/Linux58curl -LsSf https://astral.sh/uv/install.sh | sh59 60# Windows (PowerShell)61powershell -c "irm https://astral.sh/uv/install.ps1 | iex"62 63# Using pip (if you already have Python)64pip install uv65 66# Using Homebrew (macOS)67brew install uv68 69# Using cargo (if you have Rust)70cargo install --git https://github.com/astral-sh/uv uv71```72 73### Verify Installation74 75```bash76uv --version77# uv 0.x.x78```79 80## Quick Start81 82### Create a New Project83 84```bash85# Create new project with virtual environment86uv init my-project87cd my-project88 89# Or create in current directory90uv init .91 92# Initialize creates:93# - .python-version (Python version)94# - pyproject.toml (project config)95# - README.md96# - .gitignore97```98 99### Install Dependencies100 101```bash102# Install packages (creates venv if needed)103uv add requests pandas104 105# Install dev dependencies106uv add --dev pytest black ruff107 108# Install from requirements.txt109uv pip install -r requirements.txt110 111# Install from pyproject.toml112uv sync113```114 115## Virtual Environment Management116 117### Pattern 1: Creating Virtual Environments118 119```bash120# Create virtual environment with uv121uv venv122 123# Create with specific Python version124uv venv --python 3.12125 126# Create with custom name127uv venv my-env128 129# Create with system site packages130uv venv --system-site-packages131 132# Specify location133uv venv /path/to/venv134```135 136### Pattern 2: Activating Virtual Environments137 138```bash139# Linux/macOS140source .venv/bin/activate141 142# Windows (Command Prompt)143.venv\Scripts\activate.bat144 145# Windows (PowerShell)146.venv\Scripts\Activate.ps1147 148# Or use uv run (no activation needed)149uv run python script.py150uv run pytest151```152 153### Pattern 3: Using uv run154 155```bash156# Run Python script (auto-activates venv)157uv run python app.py158 159# Run installed CLI tool160uv run black .161uv run pytest162 163# Run with specific Python version164uv run --python 3.11 python script.py165 166# Pass arguments167uv run python script.py --arg value168```169 170## Package Management171 172### Pattern 4: Adding Dependencies173 174```bash175# Add package (adds to pyproject.toml)176uv add requests177 178# Add with version constraint179uv add "django>=4.0,<5.0"180 181# Add multiple packages182uv add numpy pandas matplotlib183 184# Add dev dependency185uv add --dev pytest pytest-cov186 187# Add optional dependency group188uv add --optional docs sphinx189 190# Add from git191uv add git+https://github.com/user/repo.git192 193# Add from git with specific ref194uv add git+https://github.com/user/repo.git@v1.0.0195 196# Add from local path197uv add ./local-package198 199# Add editable local package200uv add -e ./local-package201```202 203### Pattern 5: Removing Dependencies204 205```bash206# Remove package207uv remove requests208 209# Remove dev dependency210uv remove --dev pytest211 212# Remove multiple packages213uv remove numpy pandas matplotlib214```215 216### Pattern 6: Upgrading Dependencies217 218```bash219# Upgrade specific package220uv add --upgrade requests221 222# Upgrade all packages223uv sync --upgrade224 225# Upgrade package to latest226uv add --upgrade requests227 228# Show what would be upgraded229uv tree --outdated230```231 232### Pattern 7: Locking Dependencies233 234```bash235# Generate uv.lock file236uv lock237 238# Update lock file239uv lock --upgrade240 241# Lock without installing242uv lock --no-install243 244# Lock specific package245uv lock --upgrade-package requests246```247 248## Python Version Management249 250### Pattern 8: Installing Python Versions251 252```bash253# Install Python version254uv python install 3.12255 256# Install multiple versions257uv python install 3.11 3.12 3.13258 259# Install latest version260uv python install261 262# List installed versions263uv python list264 265# Find available versions266uv python list --all-versions267```268 269### Pattern 9: Setting Python Version270 271```bash272# Set Python version for project273uv python pin 3.12274 275# This creates/updates .python-version file276 277# Use specific Python version for command278uv --python 3.11 run python script.py279 280# Create venv with specific version281uv venv --python 3.12282```283 284## Project Configuration285 286### Pattern 10: pyproject.toml with uv287 288```toml289[project]290name = "my-project"291version = "0.1.0"292description = "My awesome project"293readme = "README.md"294requires-python = ">=3.8"295dependencies = [296    "requests>=2.31.0",297    "pydantic>=2.0.0",298    "click>=8.1.0",299]300 301[project.optional-dependencies]302dev = [303    "pytest>=7.4.0",304    "pytest-cov>=4.1.0",305    "black>=23.0.0",306    "ruff>=0.1.0",307    "mypy>=1.5.0",308]309docs = [310    "sphinx>=7.0.0",311    "sphinx-rtd-theme>=1.3.0",312]313 314[build-system]315requires = ["hatchling"]316build-backend = "hatchling.build"317 318[tool.uv]319dev-dependencies = [320    # Additional dev dependencies managed by uv321]322 323[tool.uv.sources]324# Custom package sources325my-package = { git = "https://github.com/user/repo.git" }326```327 328### Pattern 11: Using uv with Existing Projects329 330```bash331# Migrate from requirements.txt332uv add -r requirements.txt333 334# Migrate from poetry335# Already have pyproject.toml, just use:336uv sync337 338# Export to requirements.txt339uv pip freeze > requirements.txt340 341# Export with hashes342uv pip freeze --require-hashes > requirements.txt343```344 345For advanced workflows including Docker integration, lockfile management, performance optimization, tool comparison, common workflows, tool integration, troubleshooting, best practices, migration guides, and command reference, see [references/advanced-patterns.md](references/advanced-patterns.md)