Astral uv & Modern Python Tooling Master Cheat Sheet

# Standalone installer for Linux and macOS (No Python dependency required)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Alternatively, install via Homebrew on macOS
brew install uv

# Verify installation and active Rust engine version
uv --version

Installs the self-contained uv binary without requiring an existing Python runtime.

# 1. Create a modern virtual environment with Python 3.12 in ~12 milliseconds
uv venv --python 3.12 .venv

# 2. Activate the virtual environment (Standard command)
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Fast installation of complex multi-gigabyte data science wheels
uv pip install fastapi uvicorn "pydantic>=2.0" torch

# 4. Compile unpinned requirements.in into an exact deterministic lockfile
uv pip compile requirements.in -o requirements.txt

# 5. Strict synchronization: uninstalls any extra package not in requirements.txt
uv pip sync requirements.txt

Replaces legacy virtualenv and pip commands with drop-in, multi-threaded Rust equivalents.

# List all available Python interpreters (Local and Remote)
uv python list

# Download and install specific CPython versions
uv python install 3.11 3.12 3.13

# Install PyPy for high-throughput JIT workloads
uv python install pypy@3.10

# Pin the current repository to a specific Python version (Creates .python-version)
uv python pin 3.12

# Run an ad-hoc command against an explicit Python version without installing it globally
uv run --python 3.10 -c "import sys; print(sys.version)"

Installs and switches Python interpreter versions instantly without compiling from source.

# 1. Initialize a new modern Python application project
uv init my-service
cd my-service

# 2. Add dependencies (Updates pyproject.toml and resolves uv.lock automatically)
uv add fastapi "uvicorn[standard]" httpx

# 3. Add development-only dependencies (e.g. testing and linting tools)
uv add --dev pytest ruff mypy

# 4. Execute application inside the synchronized virtualenv (Zero manual activation)
uv run uvicorn main:app --reload

# 5. In CI/CD pipelines: install exact dependencies strictly matching lockfile
uv sync --frozen --no-dev

Full project lifecycle workflow from initialization and dependency addition to CI lockfile enforcement.

# Save the following as 'scrape.py':
cat << 'EOF' > scrape.py
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests",
#   "beautifulsoup4",
# ]
# ///

import requests
from bs4 import BeautifulSoup

resp = requests.get("https://example.com")
soup = BeautifulSoup(resp.text, "html.parser")
print("Page Title:", soup.title.string)
EOF

# Execute script with automatic on-the-fly dependency provisioning:
uv run scrape.py

Executes standalone scripts declaring self-contained dependencies via PEP 723 metadata.

# syntax=docker/dockerfile:1
FROM python:3.12-slim-bookworm AS builder

# Install uv from official standalone image
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

WORKDIR /app

# Enable bytecode compilation and use system environment in container
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

# 1. Cache dependency installation separately from application code
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev

# 2. Copy application source and finalize sync
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

# Final production stage
FROM python:3.12-slim-bookworm

WORKDIR /app
COPY --from=builder /app /app
ENV PATH="/app/.venv/bin:$PATH"

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Production Dockerfile achieving sub-second cached rebuilds using uv BuildKit cache mounts.