| 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. |
UV Package Manager
Comprehensive guide to using uv, an extremely fast Python package installer
and resolver written in Rust, for modern Python project management and
dependency workflows.
When to Use This Skill
- Setting up new Python projects quickly
- Managing Python dependencies faster than pip
- Creating and managing virtual environments
- Installing Python interpreters
- Resolving dependency conflicts efficiently
- Migrating from pip/pip-tools/poetry
- Speeding up CI/CD pipelines
- Managing monorepo Python projects
- Working with lockfiles for reproducible builds
- Optimizing Docker builds with Python dependencies
Core Concepts
1. What is uv?
- Ultra-fast package installer: 10-100x faster than pip
- Written in Rust: Leverages Rust's performance
- Drop-in pip replacement: Compatible with pip workflows
- Virtual environment manager: Create and manage venvs
- Python installer: Download and manage Python versions
- Resolver: Advanced dependency resolution
- Lockfile support: Reproducible installations
2. Key Features
- Blazing fast installation speeds
- Disk space efficient with global cache
- Compatible with pip, pip-tools, poetry
- Comprehensive dependency resolution
- Cross-platform support (Linux, macOS, Windows)
- No Python required for installation
- Built-in virtual environment support
3. UV vs Traditional Tools
- vs pip: 10-100x faster, better resolver
- vs pip-tools: Faster, simpler, better UX
- vs poetry: Faster, less opinionated, lighter
- vs conda: Faster, Python-focused
Installation
Quick Install
curl -LsSf https://astral.sh/uv/install.sh | sh
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
pip install uv
brew install uv
cargo install --git https://github.com/astral-sh/uv uv
Verify Installation
uv --version
Quick Start
Create a New Project
uv init my-project
cd my-project
uv init .
Install Dependencies
uv add requests pandas
uv add --dev pytest black ruff
uv pip install -r requirements.txt
uv sync
Virtual Environment Management
Pattern 1: Creating Virtual Environments
uv venv
uv venv --python 3.12
uv venv my-env
uv venv --system-site-packages
uv venv /path/to/venv
Pattern 2: Activating Virtual Environments
source .venv/bin/activate
.venv\Scripts\activate.bat
.venv\Scripts\Activate.ps1
uv run python script.py
uv run pytest
Pattern 3: Using uv run
uv run python app.py
uv run black .
uv run pytest
uv run --python 3.11 python script.py
uv run python script.py --arg value
Package Management
Pattern 4: Adding Dependencies
uv add requests
uv add "django>=4.0,<5.0"
uv add numpy pandas matplotlib
uv add --dev pytest pytest-cov
uv add --optional docs sphinx
uv add git+https://github.com/user/repo.git
uv add git+https://github.com/user/repo.git@v1.0.0
uv add ./local-package
uv add -e ./local-package
Pattern 5: Removing Dependencies
uv remove requests
uv remove --dev pytest
uv remove numpy pandas matplotlib
Pattern 6: Upgrading Dependencies
uv add --upgrade requests
uv sync --upgrade
uv add --upgrade requests
uv tree --outdated
Pattern 7: Locking Dependencies
uv lock
uv lock --upgrade
uv lock --no-install
uv lock --upgrade-package requests
Python Version Management
Pattern 8: Installing Python Versions
uv python install 3.12
uv python install 3.11 3.12 3.13
uv python install
uv python list
uv python list --all-versions
Pattern 9: Setting Python Version
uv python pin 3.12
uv --python 3.11 run python script.py
uv venv --python 3.12
Project Configuration
Pattern 10: pyproject.toml with uv
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
"requests>=2.31.0",
"pydantic>=2.0.0",
"click>=8.1.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.4.0",
"pytest-cov>=4.1.0",
"black>=23.0.0",
"ruff>=0.1.0",
"mypy>=1.5.0",
]
docs = [
"sphinx>=7.0.0",
"sphinx-rtd-theme>=1.3.0",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.uv]
dev-dependencies = [
]
[tool.uv.sources]
my-package = { git = "https://github.com/user/repo.git" }
Pattern 11: Using uv with Existing Projects
uv add -r requirements.txt
uv sync
uv pip freeze > requirements.txt
uv pip freeze --require-hashes > requirements.txt
Advanced Workflows
Pattern 12: Monorepo Support
[tool.uv.workspace]
members = ["packages/*"]
uv sync
uv add --path ./packages/package-a
Pattern 13: CI/CD Integration
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
- name: Set up Python
run: uv python install 3.12
- name: Install dependencies
run: uv sync --all-extras --dev
- name: Run tests
run: uv run pytest
- name: Run linting
run: |
uv run ruff check .
uv run black --check .
Pattern 14: Docker Integration
# Dockerfile
FROM python:3.12-slim
# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Set working directory
WORKDIR /app
# Copy dependency files
COPY pyproject.toml uv.lock ./
# Install dependencies
RUN uv sync --frozen --no-dev
# Copy application code
COPY . .
# Run application
CMD ["uv", "run", "python", "app.py"]
Optimized multi-stage build:
# Multi-stage Dockerfile
FROM python:3.12-slim AS builder
# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
# Install dependencies to venv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable
# Runtime stage
FROM python:3.12-slim
WORKDIR /app
# Copy venv from builder
COPY --from=builder /app/.venv .venv
COPY . .
# Use venv
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]
Pattern 15: Lockfile Workflows
uv lock
uv sync --frozen
uv lock --no-install
uv lock --upgrade-package requests
uv lock --check
uv export --format requirements-txt > requirements.txt
uv export --format requirements-txt --hash > requirements.txt
Performance Optimization
Pattern 16: Using Global Cache
uv cache clean
uv cache dir
Pattern 17: Parallel Installation
uv pip install --jobs 4 package1 package2
uv pip install --jobs 1 package
Pattern 18: Offline Mode
uv pip install --offline package
uv sync --frozen --offline
Comparison with Other Tools
uv vs pip
python -m venv .venv
source .venv/bin/activate
pip install requests pandas numpy
uv venv
uv add requests pandas numpy
uv vs poetry
poetry init
poetry add requests pandas
poetry install
uv init
uv add requests pandas
uv sync
uv vs pip-tools
pip-compile requirements.in
pip-sync requirements.txt
uv lock
uv sync --frozen
Common Workflows
Pattern 19: Starting a New Project
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
uv run black .
uv run ruff check .
Pattern 20: Maintaining Existing Project
git clone https://github.com/user/project.git
cd project
uv sync
uv sync --all-extras
uv lock --upgrade
uv run python app.py
uv run pytest
uv add new-package
git add pyproject.toml uv.lock
git commit -m "Add new-package dependency"
Tool Integration
Pattern 21: Pre-commit Hooks
repos:
- repo: local
hooks:
- id: uv-lock
name: uv lock
entry: uv lock
language: system
pass_filenames: false
- id: ruff
name: ruff
entry: uv run ruff check --fix
language: system
types: [python]
- id: black
name: black
entry: uv run black
language: system
types: [python]
Pattern 22: VS Code Integration
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.terminal.activateEnvironment": true,
"python.testing.pytestEnabled": true,
"python.testing.pytestArgs": ["-v"],
"python.linting.enabled": true,
"python.formatting.provider": "black",
"[python]": {
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": true
}
}
Troubleshooting
Common Issues
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
uv python pin 3.12
uv venv --python 3.12
uv lock --verbose
uv cache clean
uv lock --upgrade
Best Practices
Project Setup
- Always use lockfiles for reproducibility
- Pin Python version with .python-version
- Separate dev dependencies from production
- Use uv run instead of activating venv
- Commit uv.lock to version control
- Use --frozen in CI for consistent builds
- Leverage global cache for speed
- Use workspace for monorepos
- Export requirements.txt for compatibility
- Keep uv updated for latest features
Performance Tips
uv sync --frozen
uv sync --offline
uv sync --frozen
Migration Guide
From pip + requirements.txt
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uv venv
uv pip install -r requirements.txt
uv init
uv add -r requirements.txt
From Poetry
poetry install
poetry add requests
uv sync
uv add requests
From pip-tools
pip-compile requirements.in
pip-sync requirements.txt
uv lock
uv sync --frozen
Command Reference
Essential Commands
uv init [PATH]
uv add PACKAGE
uv remove PACKAGE
uv sync
uv lock
uv venv [PATH]
uv run COMMAND
uv python install VERSION
uv python list
uv python pin VERSION
uv pip install PACKAGE
uv pip uninstall PACKAGE
uv pip freeze
uv pip list
uv cache clean
uv cache dir
uv --version
Resources
Best Practices Summary
- Use uv for all new projects - Start with
uv init
- Commit lockfiles - Ensure reproducible builds
- Pin Python versions - Use .python-version
- Use uv run - Avoid manual venv activation
- Leverage caching - Let uv manage global cache
- Use --frozen in CI - Exact reproduction
- Keep uv updated - Fast-moving project
- Use workspaces - For monorepo projects
- Export for compatibility - Generate requirements.txt when needed
- Read the docs - uv is feature-rich and evolving