---
name: uv-package-manager
description: 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.
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# UV Package Manager

An extremely fast Python package installer and resolver written in Rust. 10-100x faster than pip.

## When to Use This Skill

- Setting up new Python projects or managing dependencies
- Creating/managing virtual environments and Python versions
- Migrating from pip/pip-tools/poetry to uv
- Optimizing CI/CD pipelines and Docker builds for Python
- Working with lockfiles for reproducible builds
- Managing monorepo Python projects

## Reference Files

- `references/command-reference.md` — Full command reference and troubleshooting
- `references/configuration-examples.md` — pyproject.toml, workspace, VS Code, lockfile workflows
- `references/ci-docker-integration.md` — GitHub Actions, Dockerfile, pre-commit hooks
- `references/migration-guide.md` — Migration from pip/poetry/pip-tools, speed comparisons

## Core Concepts

- **10-100x faster** than pip, written in Rust
- **Drop-in pip replacement** with compatible CLI (`uv pip install`)
- **Built-in venv manager** — creates and manages virtual environments
- **Built-in Python installer** — download and manage Python versions
- **Lockfile support** — `uv.lock` for reproducible installations
- **Global cache** — disk-efficient, shared across projects
- **Workspace support** — monorepo with multiple packages

## Installation

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# pip
pip install uv
```

## Quick Start

```bash
# New project
uv init my-project && cd my-project

# Add dependencies
uv add requests pandas
uv add --dev pytest black ruff

# Run commands (auto-activates venv)
uv run pytest
uv run python app.py

# Lock and sync
uv lock
uv sync --frozen
```

## Essential Patterns

### Virtual Environments

```bash
# Create venv (default: .venv)
uv venv
uv venv --python 3.12          # Specific Python version

# Activate (traditional)
source .venv/bin/activate       # Linux/macOS

# Or skip activation entirely — use uv run
uv run python script.py
uv run pytest
uv run --python 3.11 python script.py
```

### Adding Dependencies

```bash
uv add requests                 # Add to pyproject.toml
uv add "django>=4.0,<5.0"     # Version constraint
uv add numpy pandas matplotlib # Multiple packages
uv add --dev pytest pytest-cov # Dev dependency
uv add --optional docs sphinx  # Optional group
uv add git+https://github.com/user/repo.git      # From git
uv add git+https://github.com/user/repo.git@v1.0 # Specific ref
uv add -e ./local-package      # Editable local package
```

### Removing and Upgrading

```bash
uv remove requests             # Remove package
uv add --upgrade requests      # Upgrade specific package
uv sync --upgrade              # Upgrade all packages
uv tree --outdated             # Show outdated packages
```

### Python Version Management

```bash
uv python install 3.12         # Install Python
uv python install 3.11 3.12    # Install multiple
uv python list                 # List installed
uv python pin 3.12             # Pin version (.python-version)
```

### Lockfiles

```bash
uv lock                        # Create/update uv.lock
uv sync --frozen               # Install exact locked versions (CI)
uv lock --upgrade-package requests  # Upgrade one package in lock
uv lock --check                # Verify lockfile is current
uv export --format requirements-txt > requirements.txt  # Export
```

### Install from requirements.txt

```bash
uv pip install -r requirements.txt   # pip-compatible install
uv add -r requirements.txt           # Migrate into pyproject.toml
```

## Key Workflows

### New Project Setup

```bash
uv init my-project
cd my-project
uv python pin 3.12
uv add fastapi uvicorn pydantic
uv add --dev pytest black ruff mypy
mkdir -p src/my_project tests
uv run pytest
```

### Clone and Work on Existing Project

```bash
git clone https://github.com/user/project.git
cd project
uv sync                        # Install everything (creates venv)
uv sync --all-extras           # Include all optional groups
uv run pytest
```

### CI/CD (GitHub Actions — quick reference)

```yaml
- uses: astral-sh/setup-uv@v2
  with:
    enable-cache: true
- run: uv python install 3.12
- run: uv sync --all-extras --dev
- run: uv run pytest
```

> Full CI/CD and Docker examples: `references/ci-docker-integration.md`

### Docker (quick reference)

```dockerfile
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
```

> Full Dockerfile and multi-stage builds: `references/ci-docker-integration.md`

### Monorepo / Workspace

```toml
# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]
```

```bash
uv sync                        # Install all workspace packages
uv add --path ./packages/pkg-a # Add workspace dependency
```

> Full config: `references/configuration-examples.md`

## Best Practices

1. **Use `uv run`** instead of activating venvs manually
2. **Commit `uv.lock`** to version control for reproducibility
3. **Pin Python version** with `uv python pin` / `.python-version`
4. **Use `--frozen` in CI** for exact, reproducible installs
5. **Separate dev deps** with `uv add --dev`
6. **Use workspaces** for monorepos
7. **Export `requirements.txt`** when needed for compatibility
8. **Use `uv init`** for all new projects
9. **Leverage global cache** — uv shares cache across projects automatically
10. **Keep uv updated** — fast-moving project with frequent improvements

## Quick Command Cheat Sheet

| Task | Command |
|------|---------|
| New project | `uv init my-project` |
| Add package | `uv add requests` |
| Add dev dep | `uv add --dev pytest` |
| Remove package | `uv remove requests` |
| Install all deps | `uv sync` |
| Lock deps | `uv lock` |
| Run command | `uv run pytest` |
| Create venv | `uv venv` |
| Install Python | `uv python install 3.12` |
| Pin Python | `uv python pin 3.12` |
| Frozen install (CI) | `uv sync --frozen` |
| Upgrade all | `uv sync --upgrade` |
| Clear cache | `uv cache clean` |
| Dep tree | `uv tree` |
| Export lockfile | `uv export --format requirements-txt` |

> Full command reference and troubleshooting: `references/command-reference.md`
> Migration from pip/poetry/pip-tools: `references/migration-guide.md`

## Resources

- **Docs**: https://docs.astral.sh/uv/
- **GitHub**: https://github.com/astral-sh/uv
- **Migration guides**: https://docs.astral.sh/uv/guides/
