↓ Skip to main content
Python, Docker, Linux & More

UV Cheatsheet for Expert Python Developers

·2027 words·10 mins·
Table of Contents
Photo by David Clode on Unsplash

uv is an extremely fast Python package and project manager, written in Rust. It’s designed as a unified replacement for pip, pip-tools, pipx, poetry, pyenv, and virtualenv, offering 10-100x faster performance while maintaining compatibility with the Python packaging ecosystem.

uv is actively developed by Astral, the same company behind Ruff. It’s rapidly becoming the standard for modern Python package and project management.

Why uv?
#

For expert Python developers, uv offers several compelling advantages:

  • Blazing Fast: 10-100x faster than pip thanks to Rust implementation
  • Reliable: Built-in dependency resolution
  • Unified Tool: Replaces pip, pip-tools, pipx, poetry, pyenv, and virtualenv
  • Modern: Supports latest PEP standards and pyproject.toml
  • Python Management: Can install and manage Python versions itself

Installation
#

# Install on macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install on Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install via pip (if you must)
pip install uv

# Verify installation
uv --version

Python Version Management
#

Install Python Versions
#

# List available Python versions
uv python list

# Install a specific Python version
uv python install 3.12

# Install multiple versions
uv python install 3.11 3.12 3.13

# List installed Python versions
uv python list --only-installed

# Set default Python version
uv python pin 3.12

Virtual Environment Management
#

Create Virtual Environments
#

# Create a new virtual environment
uv venv

# Create with specific Python version (auto-downloads if needed)
uv venv --python 3.12

# Create in custom location
uv venv .venv-custom

# Create with specific Python executable
uv venv --python /usr/bin/python3.11

# Create with seed packages
uv venv --seed

Activate Virtual Environments
#

# Linux/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Package Installation (Modern Project Mode)
#

Basic Installation with uv add
#

# Add a single package
uv add requests

# Add multiple packages
uv add requests numpy pandas

# Add specific version
uv add "django==4.2.0"

# Add with version constraints
uv add "fastapi>=0.100.0,<1.0.0"

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

# Add with extras
uv add "fastapi[all]"

Advanced Installation with uv add
#

# Add from git repository
uv add "package @ git+https://github.com/user/repo.git"

# Add from specific branch/tag/commit
uv add "package @ git+https://github.com/user/repo.git@main"
uv add "package @ git+https://github.com/user/repo.git@v1.2.3"

# Add from local path
uv add --editable /path/to/local/package

# Remove a package
uv remove requests

Package Installation (pip-compatible Mode)
#

Use these commands when working with existing pip-based workflows or in virtual environments without a project structure.

Basic Installation with uv pip
#

# Install a single package
uv pip install requests

# Install multiple packages
uv pip install requests numpy pandas

# Install specific version
uv pip install "django==4.2.0"

# Install with version constraints
uv pip install "fastapi>=0.100.0,<1.0.0"

# Install from requirements.txt
uv pip install -r requirements.txt

# Install in editable mode (development)
uv pip install -e .

Advanced Installation Options
#

# Install with extras
uv pip install "fastapi[all]"

# Install from git repository
uv pip install git+https://github.com/user/repo.git

# Install from specific branch/tag/commit
uv pip install git+https://github.com/user/repo.git@main
uv pip install git+https://github.com/user/repo.git@v1.2.3
uv pip install git+https://github.com/user/repo.git@abc123

# Install from local path
uv pip install /path/to/local/package

# Install from wheel file
uv pip install package-1.0.0-py3-none-any.whl

Install with Extra Index URLs
#

# Use alternative PyPI mirror
uv pip install --index-url https://pypi.org/simple/ package

# Add extra index URL
uv pip install --extra-index-url https://custom.pypi.org/simple/ package

# Use trusted host (for internal repos)
uv pip install --trusted-host custom.pypi.org package

Package Management
#

Modern Project Mode
#

# Upgrade a specific package
uv add --upgrade requests

# Upgrade all dependencies
uv lock --upgrade

# Remove a package
uv remove requests

# Remove multiple packages
uv remove requests numpy pandas

# List project dependencies
uv tree

# Show package details
uv show package-name

Dependency Resolution and Locking
#

# Create/update lock file
uv lock

# Sync environment to match uv.lock
uv sync

# Sync only production dependencies (exclude dev)
uv sync --no-dev

# Upgrade all dependencies and update lock
uv lock --upgrade

# Upgrade specific package
uv lock --upgrade-package requests

# Export lock file to requirements.txt format
uv export --format requirements-txt > requirements.txt

Advanced Features
#

Working with pyproject.toml
#

# Modern approach: sync from pyproject.toml
uv sync

# Install with specific extras
uv sync --extra dev
uv sync --extra dev --extra test
uv sync --all-extras

# Legacy pip-compatible approach
uv pip install -e .
uv pip install -e ".[dev]"
uv pip install -e ".[dev,test]"

Lock Files
#

# Modern approach: uv.lock
uv lock                          # Create/update lock file
uv sync                          # Install from lock file

# Legacy approach: requirements.txt
uv pip compile pyproject.toml -o requirements.lock
uv pip sync requirements.lock

Environment Variables
#

# Set custom cache directory
export UV_CACHE_DIR=/custom/cache/path

# Disable cache
export UV_NO_CACHE=1

# Set link mode (copy, hardlink, symlink, clone, hardlink-or-copy)
export UV_LINK_MODE=copy

# Verbose output
export UV_VERBOSE=1

# Configure Python install directory
export UV_PYTHON_INSTALL_DIR=/custom/python/path

# Use system Python only (don't manage Python versions)
export UV_SYSTEM_PYTHON=1

# Concurrent downloads
export UV_CONCURRENT_DOWNLOADS=10

# Disable parallel installation
export UV_NO_PARALLEL=1

Performance Tuning
#

# Use more concurrent downloads
UV_CONCURRENT_DOWNLOADS=10 uv sync

# Disable parallel installation
UV_NO_PARALLEL=1 uv add package

# Use system Python (skip discovery)
uv venv --system-site-packages

Project Management (Modern Approach)
#

Initialize a New Project
#

# Create a new Python project with pyproject.toml
uv init my-project
cd my-project

# Initialize in existing directory
uv init

# Add dependencies
uv add fastapi sqlalchemy

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

# Run commands in the project environment
uv run python script.py
uv run pytest

# Build the project
uv build

Common Workflows
#

Setting Up a New Project (Modern Approach)
#

# Create and initialize project
uv init my-project
cd my-project

# Add dependencies
uv add fastapi uvicorn sqlalchemy

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

# Create lock file
uv lock

# Sync environment
uv sync

# Run your application
uv run python main.py

Setting Up a New Project (Legacy pip-tools Style)
#

# Create project directory
mkdir my-project && cd my-project

# Initialize virtual environment
uv venv

# Activate environment
source .venv/bin/activate

# Create requirements.in
cat > requirements.in << EOF
fastapi>=0.100.0
uvicorn[standard]
sqlalchemy>=2.0.0
EOF

# Compile and install dependencies
uv pip compile requirements.in -o requirements.txt
uv pip install -r requirements.txt

Upgrading Dependencies
#

# Modern approach
uv lock --upgrade                # Upgrade all
uv lock --upgrade-package requests  # Upgrade specific package
uv sync                          # Apply changes

# Legacy pip-tools approach
uv pip compile --upgrade requirements.in -o requirements.txt
uv pip sync requirements.txt

# Upgrade single dependency (legacy)
uv pip compile --upgrade-package requests requirements.in -o requirements.txt
uv pip sync requirements.txt

Managing Dev and Prod Dependencies
#

# Modern approach
uv add --dev pytest black ruff mypy
uv sync                    # Install all (dev + prod)
uv sync --no-dev          # Install only prod

# Legacy pip-tools approach
# requirements.in (production)
fastapi>=0.100.0
sqlalchemy>=2.0.0

# requirements-dev.in (development)
-c requirements.txt
pytest>=7.0.0
black
ruff
mypy

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

# Install both
uv pip sync requirements.txt requirements-dev.txt

Tool-Specific Commands
#

Running Scripts with uvx (pipx alternative)
#

# Run a tool without installing it
uvx ruff check .

# Run specific version
uvx ruff@0.1.0 check .

# Run tool from git repository
uvx --from git+https://github.com/user/tool tool-command

# List available tools
uvx --help

Using uv run (Similar to poetry run)
#

# Run a script in the project environment
uv run python script.py

# Run tests
uv run pytest

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

# Run external commands
uv run black .
uv run mypy src/

Migration from Other Tools
#

From pip
#

# Before (pip)
pip install requests
pip install -r requirements.txt
pip freeze > requirements.txt

# After (uv) - pip compatibility mode
uv pip install requests
uv pip install -r requirements.txt
uv pip freeze > requirements.txt

# Or (uv) - modern project mode
uv add requests
uv sync

From pip-tools
#

# Before (pip-tools)
pip-compile requirements.in
pip-sync requirements.txt

# After (uv)
uv pip compile requirements.in
uv pip sync requirements.txt

From poetry
#

# Before (poetry)
poetry add requests
poetry install
poetry run python script.py

# After (uv)
uv add requests
uv sync
uv run python script.py

From pipx
#

# Before (pipx)
pipx install ruff
pipx run black

# After (uvx)
uvx ruff  # Runs directly without installing
uvx black

From virtualenv/venv
#

# Before
python -m venv .venv
source .venv/bin/activate

# After
uv venv
source .venv/bin/activate

Tips and Best Practices
#

1. Use Modern Project Mode for New Projects
#

For new projects, use uv init and uv add instead of managing requirements files manually:

uv init my-project
cd my-project
uv add fastapi uvicorn
uv add --dev pytest black ruff

This generates a pyproject.toml and uv.lock file automatically.

2. Use Lock Files for Reproducibility
#

Always commit your lock files to version control for reproducible builds:

# Modern project mode (recommended)
git add pyproject.toml uv.lock

# Legacy pip-tools mode
uv pip compile requirements.in -o requirements.txt
git add requirements.txt

3. Separate Dev and Prod Dependencies
#

Modern project mode:

uv add --dev pytest black ruff mypy

Legacy pip-tools mode:

# requirements-dev.in
-c requirements.txt
pytest
black

4. Leverage the Global Cache
#

uv’s global cache dramatically speeds up environment creation. Don’t disable it unless necessary.

5. Use Version Constraints Wisely
#

# Good: Allows patch updates
fastapi>=0.100.0,<0.101.0

# Better: Using compatible release
fastapi~=0.100.0

# Modern way with uv add
uv add "fastapi>=0.100.0,<0.101.0"

# Be specific in lock files
# But flexible in pyproject.toml or requirements.in

6. Use uvx for One-Off Tool Execution
#

Instead of installing tools globally, use uvx to run them directly:

uvx ruff check .
uvx black .
uvx mypy src/

7. Automate with Pre-commit Hooks
#

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: uv-lock
        name: Update uv.lock
        entry: uv lock
        language: system
        files: pyproject.toml
        pass_filenames: false

Troubleshooting
#

Clear Cache
#

# Clear entire cache
uv cache clean

# Or manually
rm -rf ~/.cache/uv

# Or use environment variable
UV_NO_CACHE=1 uv sync

Debug Dependency Resolution
#

# Verbose output (modern)
uv add -v package
uv sync -v

# Very verbose output
uv add -vv package

# Verbose output (pip-compatible)
uv pip install -v package
uv pip install -vv package

Handle SSL Issues
#

# Use trusted host (pip-compatible mode)
uv pip install --trusted-host pypi.org package

# Or set environment variable
export UV_INSECURE=1

Performance Comparison
#

Here’s a real-world comparison installing a medium-sized project:

# pip (traditional)
time pip install -r requirements.txt
# ~45 seconds

# pip with cache
time pip install -r requirements.txt
# ~15 seconds

# uv in pip-compatible mode (first run)
time uv pip install -r requirements.txt
# ~5 seconds

# uv in pip-compatible mode (cached)
time uv pip install -r requirements.txt
# ~1 second

# uv modern mode (first run)
time uv sync
# ~3 seconds

# uv modern mode (cached)
time uv sync
# ~0.5 seconds

Quick Reference Card
#

# Python management
uv python install 3.12           # Install Python version
uv python list                   # List available versions
uv python pin 3.12               # Pin project to Python version

# Project management (modern - recommended)
uv init                          # Initialize new project
uv add package                   # Add dependency
uv add --dev package             # Add dev dependency
uv remove package                # Remove dependency
uv lock                          # Create/update lock file
uv sync                          # Sync dependencies from lock
uv sync --no-dev                 # Sync prod dependencies only
uv run script.py                 # Run in project env
uv build                         # Build project
uv tree                          # Show dependency tree
uv export > requirements.txt     # Export to requirements.txt

# Tool execution (pipx alternative)
uvx ruff check .                 # Run tool without installing
uvx black .                      # Run black formatter
uvx --from package==1.0 tool     # Run specific version

# Virtual environments
uv venv                          # Create venv
uv venv --python 3.12            # Create with specific Python

# Pip compatibility (legacy workflows)
uv pip install package           # Install package
uv pip compile requirements.in   # Compile dependencies
uv pip sync requirements.txt     # Sync to requirements
uv pip list                      # List packages
uv pip freeze                    # Freeze dependencies

References
#