Uv

uv Skill

Extremely fast Python package and project manager by Astral (Ruff creators).

Overview

uv is a single tool that replaces:

• pip/pip-tools - Package installation and dependency resolution
• virtualenv/venv - Virtual environment creation
• pyenv - Python version management
• pipx - Tool installation and execution
• poetry/pdm - Project and dependency management
• twine - Package publishing

Key Features:

• 10-100x faster than pip
• Universal lockfile (uv.lock) for reproducible builds
• Automatic Python version management
• Built-in tool execution (uvx)
• PEP 723 inline script dependencies
• Drop-in pip compatibility

Quick Reference

Quick Start

Installation

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

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

# Via pip/pipx
pipx install uv
pip install uv

# Homebrew
brew install uv

Shell Completion

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

Essential Commands

1. Starting a Project

# Create new project
uv init my-project          # Application (default)
uv init --lib my-library    # Library (src layout, build backend)
uv init --app my-app        # Explicit application

# Set Python version
uv python pin 3.12          # Creates .python-version

# Install Python if needed
uv python install 3.12

2. Managing Dependencies

# Add packages
uv add requests flask       # Production dependencies
uv add --dev pytest ruff    # Development dependencies
uv add --group test pytest  # Specific dependency group
uv add --optional api flask # Optional extra
uv add "httpx>=0.20"        # With version constraint

# Remove packages
uv remove requests
uv remove --dev pytest

# Update packages
uv lock --upgrade                    # All packages
uv lock --upgrade-package requests   # Single package

# View dependencies
uv tree                     # Full tree
uv tree --depth 2           # Limited depth

3. Syncing Environment

# Install all dependencies
uv sync                     # Default (includes dev)
uv sync --locked            # CI/production (strict)
uv sync --frozen            # Don't update lockfile
uv sync --no-dev            # Exclude dev dependencies
uv sync --all-extras        # Include optional extras

4. Running Code

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

# Run with temporary dependency
uv run --with pandas script.py

# Run tools without installing (uvx)
uvx ruff check .
uvx black --check .
uvx --from httpie http https://example.com

5. Python Version Management

# Install Python versions
uv python install           # Latest version
uv python install 3.12      # Specific version
uv python install 3.11 3.12 3.13  # Multiple

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

# Pin version
uv python pin 3.12          # Project (.python-version)
uv python pin --global 3.12 # User default

# Find Python
uv python find
uv python find ">=3.11"

6. Virtual Environments

# Create (usually automatic)
uv venv                     # Creates .venv
uv venv my-env              # Custom name
uv venv --python 3.12       # Specific Python

# Activate (optional - uv run auto-detects)
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

7. Global Tools

# Install tools globally
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install --python 3.12 mypy

# Manage tools
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff

# Setup PATH
uv tool update-shell

Scripts with Inline Dependencies (PEP 723)

# Initialize script with metadata
uv init --script example.py --python 3.12

# Add dependencies to script
uv add --script example.py requests rich

# Run script (dependencies auto-installed)
uv run example.py

Script format:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich import print
print(requests.get("https://api.example.com").json())

pip-Compatible Interface

# Install packages (requires virtual environment)
uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .         # Editable install

# Uninstall
uv pip uninstall flask

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

# Sync from requirements
uv pip sync requirements.txt

# Freeze environment
uv pip freeze

Building and Publishing

# Build distributions
uv build                    # Creates dist/ with wheel and sdist

# Publish to PyPI
uv publish                  # Requires authentication setup

# Authenticate
uv auth login pypi          # Interactive login
uv auth login pypi --token  # API token

Project Structure

my-project/
├── pyproject.toml          # Project definition (required)
├── uv.lock                 # Lock file (auto-generated)
├── .venv/                  # Virtual environment (gitignored)
├── .python-version         # Python version pin (optional)
└── src/
    └── my_project/
        └── __init__.py

pyproject.toml Example

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
api = ["fastapi", "uvicorn"]
dev = ["pytest", "ruff"]

[project.scripts]
my-cli = "my_project.cli:main"

[dependency-groups]
dev = ["pytest>=8", "ruff", "mypy"]
test = ["pytest-cov"]
docs = ["sphinx", "myst-parser"]

[tool.uv]
dev-dependencies = ["pytest", "ruff"]  # Alternative to dependency-groups
default-groups = ["dev"]

[tool.uv.sources]
# Git dependency
my-lib = { git = "https://github.com/user/my-lib" }
# Local path
local-pkg = { path = "./packages/local-pkg" }
# Specific index
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

Configuration

Configuration Files

Project-level (highest priority):

• uv.toml - Standalone config (preferred)
• pyproject.toml - Under [tool.uv] section

User-level:

• ~/.config/uv/uv.toml (macOS/Linux)
• %APPDATA%\uv\uv.toml (Windows)

Key Environment Variables

Common Workflows

New Project Setup

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

# Add dependencies
uv add flask sqlalchemy
uv add --dev pytest ruff mypy

# Run application
uv run flask run

# Run tests
uv run pytest

Existing Project (from requirements.txt)

# Initialize uv project
uv init

# Import dependencies from requirements.txt
uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')

# Or use pip interface
uv venv
uv pip install -r requirements.txt

CI/CD Pipeline

# GitHub Actions
- uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
- run: uv sync --locked
- run: uv run pytest

# GitLab CI
variables:
  UV_CACHE_DIR: .uv-cache
  UV_LINK_MODE: copy
image: ghcr.io/astral-sh/uv:latest
script:
  - uv sync --locked
  - uv run pytest

Docker

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

# Install dependencies only (for caching)
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-install-project

# Copy source and install project
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_app"]

direnv Integration

# .envrc
if has uv; then
  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi
  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
fi

Migration Guide

From pip + requirements.txt

# Option 1: Initialize new uv project and import dependencies
uv init
# Extract package names from requirements.txt
cat requirements.txt | grep -v "^#" | grep -v "^-e" | \
  cut -d'=' -f1 | cut -d'>' -f1 | xargs uv add

# Option 2: Keep using requirements.txt with uv's pip interface
uv venv
uv pip install -r requirements.txt

# Option 3: Generate lockfile from requirements.txt
uv pip compile requirements.in -o requirements.txt

Key differences:

• uv.lock replaces requirements.txt for locking
• pyproject.toml replaces requirements.in for declaring dependencies
• Use uv run instead of activating virtualenv

From Poetry

# uv can read Poetry's pyproject.toml format
cd existing-poetry-project

# Initialize uv (keeps existing pyproject.toml)
uv sync

# Poetry sections are automatically recognized:
# [tool.poetry.dependencies] -> project dependencies
# [tool.poetry.group.dev.dependencies] -> dev dependencies

Migrate pyproject.toml (optional but recommended):

# Poetry format
[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.28"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"

# Standard format (uv native)
[project]
requires-python = ">=3.11"
dependencies = ["requests>=2.28"]

[dependency-groups]
dev = ["pytest>=8.0"]

Command equivalents:

From Pipenv

# Convert Pipfile to requirements.txt first
pipenv requirements > requirements.txt
pipenv requirements --dev > requirements-dev.txt

# Initialize uv project and import
uv init
cat requirements.txt | grep -v "^#" | xargs uv add
cat requirements-dev.txt | grep -v "^#" | xargs uv add --dev

# Remove old Pipenv files after verification
rm Pipfile Pipfile.lock

Command equivalents:

From pyenv (Python version management only)

# Install Python versions with uv instead
uv python install 3.11 3.12 3.13

# Pin version for project (creates .python-version)
uv python pin 3.12

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

# uv reads existing .python-version files from pyenv

Note: You can use pyenv and uv together - uv will detect pyenv-installed Pythons.

From conda

uv does not replace conda for:

• Non-Python dependencies (C libraries, CUDA, etc.)
• Conda-specific packages not on PyPI

For pure Python projects:

# Export conda environment
conda list --export > conda-packages.txt

# Extract Python packages (filter conda-specific ones)
grep -v "^#" conda-packages.txt | grep -v "conda" | cut -d'=' -f1 > packages.txt

# Initialize uv and add packages
uv init
uv add $(cat packages.txt | tr '\n' ' ')

Hybrid approach: Use conda for system dependencies, uv for Python packages:

# Conda for non-Python deps
conda create -n myenv python=3.12 cudatoolkit

# Activate conda env, then use uv
conda activate myenv
export UV_SYSTEM_PYTHON=1
uv pip install -r requirements.txt

Common Pitfalls

1. Forgetting --locked in CI/Production

# Wrong - may update lockfile unexpectedly
uv sync

# Correct - fails if lockfile is outdated (reproducible builds)
uv sync --locked

2. Mixing uv and pip Commands

# Don't do this - breaks uv's dependency tracking
pip install some-package
source .venv/bin/activate && pip install another-package

# Do this instead - uv tracks all dependencies
uv add some-package
# Or use uv's pip interface if needed
uv pip install some-package

3. Not Committing uv.lock

The uv.lock file must be committed to version control for reproducible builds. Without it, environments may resolve differently.

# .gitignore - DON'T ignore uv.lock
.venv/
__pycache__/
# uv.lock  <-- DO NOT ADD THIS LINE

4. Running Commands Outside Project Environment

# Wrong - uses system Python, not project environment
python script.py
pytest

# Correct - runs within project's virtual environment
uv run python script.py
uv run pytest

5. Editing uv.lock Manually

Never edit uv.lock by hand. It's auto-generated and managed by uv.

# To update a specific package
uv lock --upgrade-package requests

# To upgrade all packages
uv lock --upgrade

# To regenerate from scratch
rm uv.lock && uv lock

6. Using --frozen When You Mean --locked

# --frozen: Don't update lockfile, but don't verify it either
uv sync --frozen

# --locked: Verify lockfile matches pyproject.toml (use this in CI)
uv sync --locked

Troubleshooting

Common Issues

Debug Commands

# Check current environment
uv python find
uv pip list

# Verbose output
uv sync -v
uv sync -vv  # More verbose

# Check lockfile status
uv lock --check

# Clear cache
uv cache clean
uv cache prune --ci  # For CI environments

References

• references/cli-commands.md - Complete CLI reference
• references/project-management.md - Project and dependency management
• references/python-versions.md - Python version management
• references/integrations.md - Docker, CI/CD, and tool integrations

External Links

• Official docs: <https://docs.astral.sh/uv/>
• GitHub: <https://github.com/astral-sh/uv>
• Docker images: <https://github.com/astral-sh/uv/pkgs/container/uv>
• Changelog: <https://github.com/astral-sh/uv/blob/main/CHANGELOG.md>

---

Absorbed sub-skill (post-consolidation)

This skill now subsumes the former python-project skill (project scaffolding). Original content preserved under:

---

Gotchas

• `uv pip install -e .` works but doesn't write the editable install to `uv.lock` — the lockfile is wrong on next uv sync. Use uv add --editable instead.
• `uv sync --frozen` fails if dependencies upgraded outside the lock — won't auto-update; emit a clear error message but blocks CI until you uv lock --upgrade-package <name>.
• `uv venv` creates `.venv` in CWD — missing --directory after cd puts the venv in the wrong place. Pin with UV_PROJECT_ENVIRONMENT env var or absolute paths in scripts.
• `uv tool install` and `uv pip install` go to DIFFERENT environments — uv tools are isolated per-tool; pip-installed packages aren't visible to uv-installed tools.
• Pin via `==X.Y.Z` in `pyproject.toml` doesn't lock; only `uv.lock` does — dependencies = ["foo==1.2.3"] allows uv to pick any compatible 1.2.3, including yanked versions.

uv CLI Reference

Complete command reference for uv - the Python package and project manager.

Command Structure

uv [OPTIONS] <COMMAND>

Top-Level Commands

---

Project Commands

uv init

Create a new project.

uv init [OPTIONS] [PATH]

Options:

Examples:

uv init my-project
uv init --lib my-library
uv init --app --python 3.12 my-app
uv init --script example.py

uv add

Add dependencies to the project.

uv add [OPTIONS] <PACKAGES>...

Options:

Examples:

uv add requests flask
uv add "httpx>=0.20,<1.0"
uv add --dev pytest ruff mypy
uv add --group test pytest-cov
uv add --optional api fastapi uvicorn
uv add --script example.py pandas
uv add "git+https://github.com/user/repo"
uv add torch --index https://download.pytorch.org/whl/cpu

uv remove

Remove dependencies from the project.

uv remove [OPTIONS] <PACKAGES>...

Options:

Examples:

uv remove requests
uv remove --dev pytest
uv remove --group test pytest-cov

uv sync

Update the project's environment.

uv sync [OPTIONS]

Options:

Examples:

uv sync
uv sync --locked
uv sync --no-dev --all-extras
uv sync --group test --group lint
uv sync --no-install-project  # Dependencies only (Docker caching)

uv lock

Update the project's lockfile.

uv lock [OPTIONS]

Options:

Examples:

uv lock
uv lock --check  # CI validation
uv lock --upgrade
uv lock --upgrade-package requests
uv lock --script example.py

uv run

Run a command or script in the project environment.

uv run [OPTIONS] [COMMAND]...

Options:

Examples:

uv run python script.py
uv run pytest -v
uv run --with pandas python analyze.py
uv run -m my_module
uv run --isolated ruff check .
uv run --env-file .env.local python app.py
echo 'print("hello")' | uv run -

uv tree

Display the project's dependency tree.

uv tree [OPTIONS]

Options:

Examples:

uv tree
uv tree --depth 2
uv tree --package requests
uv tree --invert --package urllib3

uv export

Export the lockfile to alternate formats.

uv export [OPTIONS]

Options:

Examples:

uv export --format requirements-txt -o requirements.txt
uv export --format pylock.toml
uv export --format cyclonedx1.5 -o sbom.json

---

Python Management Commands

uv python install

Install Python versions.

uv python install [OPTIONS] [VERSIONS]...

Options:

Examples:

uv python install
uv python install 3.12
uv python install 3.11 3.12 3.13
uv python install pypy
uv python install 3.12 --default

uv python list

List available and installed Python versions.

uv python list [OPTIONS] [VERSION]

Options:

Examples:

uv python list
uv python list --only-installed
uv python list 3.12
uv python list pypy

uv python pin

Pin Python version for the project.

uv python pin [OPTIONS] <VERSION>

Options:

Examples:

uv python pin 3.12
uv python pin --global 3.12
uv python pin 3.12.5 --resolved

uv python find

Find Python executable.

uv python find [OPTIONS] [VERSION]

Options:

Examples:

uv python find
uv python find ">=3.11"
uv python find 3.12

uv python upgrade

Upgrade Python installations.

uv python upgrade [OPTIONS] [VERSIONS]...

Examples:

uv python upgrade 3.12  # Upgrade to latest 3.12.x
uv python upgrade       # Upgrade all installed

uv python uninstall

Uninstall Python versions.

uv python uninstall <VERSIONS>...

Examples:

uv python uninstall 3.11
uv python uninstall 3.11 3.12

---

Tool Commands

uv tool run (uvx)

Run a tool without installing.

uvx [OPTIONS] <COMMAND>...
uv tool run [OPTIONS] <COMMAND>...

Options:

Examples:

uvx ruff check .
uvx black --check .
uvx --from httpie http https://api.example.com
uvx ruff@0.5.0 check .
uvx --with mkdocs-material mkdocs build
uvx --python 3.12 mypy .

uv tool install

Install a tool globally.

uv tool install [OPTIONS] <PACKAGE>

Options:

Examples:

uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install ruff --python 3.12
uv tool install mkdocs --with mkdocs-material

uv tool list

List installed tools.

uv tool list [OPTIONS]

Options:

uv tool upgrade

Upgrade installed tools.

uv tool upgrade [OPTIONS] [TOOL]

Options:

Examples:

uv tool upgrade ruff
uv tool upgrade --all

uv tool uninstall

Uninstall a tool.

uv tool uninstall <TOOL>

uv tool update-shell

Update shell configuration for tool PATH.

uv tool update-shell

---

Virtual Environment Commands

uv venv

Create a virtual environment.

uv venv [OPTIONS] [PATH]

Options:

Examples:

uv venv
uv venv .venv
uv venv --python 3.12 my-env
uv venv --seed  # Include pip

---

pip Interface Commands

uv pip install

Install packages.

uv pip install [OPTIONS] <PACKAGES>...

Options:

Examples:

uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .
uv pip install --upgrade requests

uv pip uninstall

Uninstall packages.

uv pip uninstall [OPTIONS] <PACKAGES>...

uv pip compile

Compile requirements.

uv pip compile [OPTIONS] <SRC>...

Options:

Examples:

uv pip compile requirements.in -o requirements.txt
uv pip compile pyproject.toml -o requirements.txt
uv pip compile requirements.in --upgrade

uv pip sync

Sync environment with requirements.

uv pip sync [OPTIONS] <REQUIREMENTS>...

Examples:

uv pip sync requirements.txt

uv pip freeze

List installed packages.

uv pip freeze [OPTIONS]

uv pip list

List installed packages.

uv pip list [OPTIONS]

Options:

uv pip show

Show package information.

uv pip show <PACKAGES>...

uv pip check

Verify installed packages have compatible dependencies.

uv pip check

---

Build and Publish Commands

uv build

Build distributions.

uv build [OPTIONS] [SRC]

Options:

Examples:

uv build
uv build --wheel
uv build -o dist/

uv publish

Publish distributions.

uv publish [OPTIONS] [DIST]...

Options:

Examples:

uv publish
uv publish dist/*
uv publish --token $PYPI_TOKEN

---

Cache Commands

uv cache clean

Clear cache.

uv cache clean [PACKAGES]...

uv cache prune

Remove outdated cache entries.

uv cache prune [OPTIONS]

Options:

uv cache dir

Show cache directory path.

uv cache dir

---

Authentication Commands

uv auth login

Authenticate with a service.

uv auth login [OPTIONS] <SERVICE>

Options:

Examples:

uv auth login pypi
uv auth login pypi --token
uv auth login https://private.pypi.org

uv auth logout

Remove authentication.

uv auth logout [OPTIONS] <SERVICE>

uv auth token

Show authentication token.

uv auth token <SERVICE>

---

Global Options

Available for most commands:

---

Version Request Formats

uv accepts various Python version formats:

---

Environment Variables

See references/integrations.md for complete environment variable reference.

Key variables:

• UV_CACHE_DIR - Cache directory
• UV_PYTHON - Default Python version
• UV_INDEX_URL / UV_DEFAULT_INDEX - Package index
• UV_FROZEN - Use lockfile without updating
• UV_LOCKED - Assert lockfile unchanged
• UV_LINK_MODE - Package linking mode
• UV_COMPILE_BYTECODE - Compile .pyc files

uv Integrations Reference

Comprehensive guide to integrating uv with Docker, CI/CD, tools, and other systems.

---

Docker Integration

Official Docker Images

Distroless (uv binary only):

ghcr.io/astral-sh/uv:latest
ghcr.io/astral-sh/uv:0.9.18
ghcr.io/astral-sh/uv:0.9

With OS (Alpine):

ghcr.io/astral-sh/uv:alpine
ghcr.io/astral-sh/uv:alpine3.22

With OS (Debian):

ghcr.io/astral-sh/uv:debian-slim
ghcr.io/astral-sh/uv:bookworm-slim
ghcr.io/astral-sh/uv:trixie-slim

With Python:

ghcr.io/astral-sh/uv:python3.12-bookworm-slim
ghcr.io/astral-sh/uv:python3.12-alpine

Installing uv in Dockerfile

Copy from distroless image (recommended):

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

Pin to specific version:

COPY --from=ghcr.io/astral-sh/uv:0.9.18 /uv /uvx /bin/

Pin to SHA256:

# Use full SHA for reproducible builds
COPY --from=ghcr.io/astral-sh/uv@sha256:2381d6aa60c326b71... \
  /uv /uvx /bin/

Using installer script:

RUN apt-get update && apt-get install -y curl ca-certificates
ADD https://astral.sh/uv/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin/:$PATH"

Basic Dockerfile Pattern

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

ENV UV_NO_DEV=1
RUN uv sync --locked

COPY . .

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_app"]

Multi-Stage Build (Optimized)

# Build stage
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Install dependencies first (cache layer)
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

# Copy source and sync project
COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

# Runtime stage
FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_app"]

Non-Editable Production Build

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-editable

COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable

FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
CMD ["/app/.venv/bin/my-app"]

Docker Caching

# Enable cache mount
ENV UV_LINK_MODE=copy  # Required for separate filesystems

RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

Docker Environment Variables

ENV UV_NO_DEV=1              # Exclude dev dependencies
ENV UV_COMPILE_BYTECODE=1    # Compile .pyc files
ENV UV_LINK_MODE=copy        # Required for cache mounts
ENV UV_NO_CACHE=1            # Disable caching (smaller image)

.dockerignore

.venv/
__pycache__/
*.pyc
.git/
.pytest_cache/
.mypy_cache/
.ruff_cache/

---

GitHub Actions

Basic Setup

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Set up Python
        run: uv python install

      - name: Install dependencies
        run: uv sync --locked

      - name: Run tests
        run: uv run pytest

With Caching

- name: Install uv
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    version: "0.9.18"  # Pin version

Matrix Testing

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v5
      - uses: astral-sh/setup-uv@v7
        with:
          python-version: ${{ matrix.python-version }}
      - run: uv sync --locked
      - run: uv run pytest

Using setup-python (Faster)

- uses: actions/setup-python@v6
  with:
    python-version-file: ".python-version"

- uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true

Manual Caching

env:
  UV_CACHE_DIR: /tmp/.uv-cache

jobs:
  test:
    steps:
      - uses: actions/cache@v4
        with:
          path: /tmp/.uv-cache
          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
          restore-keys: |
            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
            uv-${{ runner.os }}

      - run: uv sync --locked
      - run: uv run pytest
      - run: uv cache prune --ci

Publishing to PyPI

name: Publish

on:
  push:
    tags:
      - v*

jobs:
  publish:
    runs-on: ubuntu-latest
    environment:
      name: pypi
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: astral-sh/setup-uv@v7

      - name: Build
        run: uv build

      - name: Publish
        run: uv publish

---

GitLab CI/CD

Basic Configuration

variables:
  UV_VERSION: "0.9.18"
  UV_CACHE_DIR: .uv-cache
  UV_LINK_MODE: copy  # Required for GitLab

test:
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python3.12-bookworm-slim
  cache:
    key:
      files:
        - uv.lock
    paths:
      - $UV_CACHE_DIR
  script:
    - uv sync --locked
    - uv run pytest
    - uv cache prune --ci

Distroless Image

test:
  image:
    name: ghcr.io/astral-sh/uv:$UV_VERSION
    entrypoint: [""]  # Required for distroless
  script:
    - uv sync --locked

Using System Python

variables:
  UV_SYSTEM_PYTHON: 1

test:
  image: python:3.12-slim
  script:
    - curl -LsSf https://astral.sh/uv/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - uv pip install -r requirements.txt

---

Pre-Commit Hooks

Configuration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.9.18
    hooks:
      # Keep uv.lock in sync with pyproject.toml
      - id: uv-lock

      # Export to requirements.txt
      - id: uv-export

Compile Requirements

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.9.18
    hooks:
      - id: pip-compile
        args: [requirements.in, -o, requirements.txt]

Multiple Requirements Files

repos:
  - repo: https://github.com/astral-sh/uv-pre-commit
    rev: 0.9.18
    hooks:
      - id: pip-compile
        name: pip-compile requirements.in
        args: [requirements.in, -o, requirements.txt]
      - id: pip-compile
        name: pip-compile requirements-dev.in
        args: [requirements-dev.in, -o, requirements-dev.txt]
        files: ^requirements-dev\.(in|txt)$

---

Tools and Scripts

Running Tools (uvx)

# One-off tool execution
uvx ruff check .
uvx black --check .
uvx mypy src/

# Specific version
uvx ruff@0.5.0 check .

# With dependencies
uvx --with mkdocs-material mkdocs build

# From different package
uvx --from httpie http https://api.example.com

Installing Tools Globally

# Install
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install --python 3.12 mypy

# List installed
uv tool list

# Upgrade
uv tool upgrade ruff
uv tool upgrade --all

# Uninstall
uv tool uninstall ruff

# Add to PATH
uv tool update-shell

Scripts with Inline Dependencies (PEP 723)

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.example.com")
print(response.json())

# Make executable and run
chmod +x script.py
./script.py

# Or run directly
uv run script.py

# Add dependencies to script
uv add --script script.py pandas

---

direnv Integration

Basic .envrc

# .envrc
if has uv; then
  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi
  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
fi

Custom Layout Function

Add to ~/.config/direnv/direnvrc:

layout_uv() {
  if ! has uv; then
    log_error "uv not found. Install from https://astral.sh/uv"
    return 1
  fi

  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi

  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
}

Usage in .envrc:

layout uv

---

IDE Integration

VS Code

settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true
}

PyCharm

1. Open Project Settings > Python Interpreter 2. Add Interpreter > Add Local Interpreter 3. Select Existing > Navigate to .venv/bin/python

---

Environment Variables Reference

Core Settings

Index Configuration

Resolution Control

Build Settings

Network Settings

Python Management

---

Common Integration Patterns

Makefile

.PHONY: install test lint format

install:
 uv sync --locked

test:
 uv run pytest -v

lint:
 uv run ruff check .
 uv run mypy src/

format:
 uv run ruff format .
 uv run ruff check --fix .

build:
 uv build

publish:
 uv publish

tox Alternative

# Run tests across Python versions
for py in 3.10 3.11 3.12; do
  uv run --python $py pytest
done

Docker Compose Development

# docker-compose.yml
services:
  app:
    build: .
    volumes:
      - .:/app
      - /app/.venv  # Preserve container's venv
    command: uv run python -m my_app

# docker-compose.override.yml (development)
services:
  app:
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - .venv/
        - action: rebuild
          path: ./pyproject.toml

Deployment Script

#!/bin/bash
set -e

# Production deployment
uv sync --locked --no-dev
uv run python -m my_app

---

Troubleshooting Integrations

Docker Issues

CI/CD Issues

Tool Issues

uv Project Management Reference

Comprehensive guide to managing Python projects with uv.

Project Structure

Core Files

my-project/
├── pyproject.toml          # Project definition (required)
├── uv.lock                  # Lock file (auto-generated)
├── .venv/                   # Virtual environment (auto-created)
├── .python-version         # Python version pin (optional)
├── README.md
└── src/
    └── my_project/
        ├── __init__.py
        └── main.py

File Purposes

---

pyproject.toml Configuration

Minimal Configuration

[project]
name = "my-project"
version = "0.1.0"

Complete Example

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome Python project"
readme = "README.md"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "you@example.com" }
]
keywords = ["python", "example"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]
requires-python = ">=3.11"

# Main dependencies
dependencies = [
    "requests>=2.28",
    "click>=8.0",
    "pydantic>=2.0",
]

# Optional dependencies (extras)
[project.optional-dependencies]
api = ["fastapi>=0.100", "uvicorn>=0.23"]
database = ["sqlalchemy>=2.0", "alembic>=1.12"]
all = ["my-project[api,database]"]

# Entry points
[project.scripts]
my-cli = "my_project.cli:main"

[project.gui-scripts]
my-gui = "my_project.gui:main"

[project.entry-points."my_project.plugins"]
plugin-a = "my_project.plugins:PluginA"

# URLs
[project.urls]
Homepage = "https://github.com/user/my-project"
Documentation = "https://my-project.readthedocs.io"
Repository = "https://github.com/user/my-project"

# Build system
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# Dependency groups (PEP 735)
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.10"]
test = ["pytest-cov>=5", "pytest-asyncio>=0.23"]
docs = ["sphinx>=7", "myst-parser>=3"]
lint = ["ruff>=0.5", "mypy>=1.10", "pre-commit>=3"]

# UV-specific configuration
[tool.uv]
# Default groups to install
default-groups = ["dev"]

# Alternative dev dependencies (deprecated, use dependency-groups)
dev-dependencies = ["pytest", "ruff"]

# Constraint dependencies
constraint-dependencies = ["grpcio<1.65"]

# Override dependencies (force specific versions)
override-dependencies = ["werkzeug==2.3.0"]

# Exclude from resolution
exclude-dependencies = ["some-package"]

# Package indexes
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "private"
url = "https://pypi.company.com/simple"

# Dependency sources
[tool.uv.sources]
# Git repository
my-lib = { git = "https://github.com/user/my-lib" }
my-lib-branch = { git = "https://github.com/user/my-lib", branch = "develop" }
my-lib-tag = { git = "https://github.com/user/my-lib", tag = "v1.0.0" }
my-lib-rev = { git = "https://github.com/user/my-lib", rev = "abc123" }

# Local path
local-pkg = { path = "./packages/local-pkg" }
local-editable = { path = "./packages/local-pkg", editable = true }

# Specific index
torch = { index = "pytorch" }

# URL
direct-pkg = { url = "https://example.com/package-1.0.0.whl" }

# Environment markers
[tool.uv.sources.jax]
marker = "sys_platform == 'linux'"

# Target environments for resolution
[tool.uv]
environments = [
    "sys_platform == 'darwin'",
    "sys_platform == 'linux'",
]

# Conflicts (mutually exclusive extras/groups)
[tool.uv]
conflicts = [
    [
        { extra = "cpu" },
        { extra = "cuda" },
    ]
]

# pip interface settings (only for uv pip commands)
[tool.uv.pip]
index-url = "https://pypi.org/simple"

---

Dependency Management

Adding Dependencies

# Add to project.dependencies
uv add requests
uv add "requests>=2.28"
uv add requests flask sqlalchemy

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

# Add to specific group
uv add --group test pytest-cov
uv add --group lint ruff mypy

# Add optional dependency (extra)
uv add --optional api fastapi uvicorn

# Add from different sources
uv add "git+https://github.com/user/repo"
uv add "git+https://github.com/user/repo@v1.0.0"
uv add "../local-package"
uv add torch --index https://download.pytorch.org/whl/cpu

# Platform-specific dependency
uv add "jax; sys_platform == 'linux'"

Removing Dependencies

uv remove requests
uv remove --dev pytest
uv remove --group test pytest-cov
uv remove --optional api fastapi

Updating Dependencies

# Upgrade all dependencies
uv lock --upgrade

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

# Change version constraint
uv add "requests>=2.30"

---

Lock File Management

Lock File Behavior

The uv.lock file:

• Contains exact resolved versions for all platforms/Python versions
• Is human-readable TOML format
• Should be committed to version control
• Is managed by uv (don't edit manually)

Lock Commands

# Create/update lock file
uv lock

# Check if lock file is up-to-date
uv lock --check

# Upgrade all packages
uv lock --upgrade

# Upgrade specific package
uv lock --upgrade-package requests
uv lock --upgrade-package "requests==2.32.0"

Lock File Freshness

Lock file is considered outdated when:

• Dependencies added/removed from pyproject.toml
• Version constraints changed to exclude locked version

Lock file remains valid when:

• New upstream versions released (explicit upgrade needed)
• Constraint changes still include locked version

---

Environment Synchronization

Basic Sync

# Sync environment (includes dev by default)
uv sync

# Use exact lockfile (CI/production)
uv sync --locked

# Don't update lockfile
uv sync --frozen

Controlling What's Installed

# Exclude development dependencies
uv sync --no-dev

# Only development dependencies
uv sync --only-dev

# Include specific group
uv sync --group test
uv sync --group test --group lint

# Exclude specific group
uv sync --no-group lint

# All groups
uv sync --all-groups

# No default groups
uv sync --no-default-groups

# Include extras (optional dependencies)
uv sync --extra api
uv sync --all-extras

# Only specific group (no project)
uv sync --only-group test

Partial Installation (Docker/CI Optimization)

# Install dependencies without project
uv sync --no-install-project

# Skip specific packages
uv sync --no-install-package dev-only-lib

# Skip workspace members
uv sync --no-install-workspace

Sync Options

# Remove extraneous packages (default)
uv sync --exact

# Keep extraneous packages
uv sync --inexact

# Non-editable install
uv sync --no-editable

---

Running Commands

Basic Execution

# Run command in project environment
uv run python script.py
uv run pytest
uv run my-cli --help

# Run Python module
uv run -m my_module

# Arguments after command passed directly
uv run pytest -v --tb=short

Execution Options

# Use lockfile only (error if outdated)
uv run --locked python script.py

# Don't check environment freshness
uv run --frozen python script.py

# Don't sync environment
uv run --no-sync python script.py

# Include temporary dependency
uv run --with pandas python analyze.py

# Isolated environment
uv run --isolated python script.py

# Load environment file
uv run --env-file .env python app.py

# Include extras
uv run --all-extras python script.py
uv run --extra api python script.py

---

Workspaces

Workspace Structure

workspace-root/
├── pyproject.toml          # Workspace root
├── uv.lock                  # Single lockfile for entire workspace
├── packages/
│   ├── package-a/
│   │   ├── pyproject.toml
│   │   └── src/
│   └── package-b/
│       ├── pyproject.toml
│       └── src/
└── apps/
    └── my-app/
        ├── pyproject.toml
        └── src/

Workspace Configuration

# workspace-root/pyproject.toml
[tool.uv.workspace]
members = ["packages/*", "apps/*"]

# Exclude patterns
exclude = ["packages/deprecated-*"]

Workspace Commands

# Sync all workspace members
uv sync --all-packages

# Run in specific package
uv run --package package-a pytest

# Add dependency to workspace member
uv add --package package-a requests

---

Dependency Groups (PEP 735)

Defining Groups

[dependency-groups]
dev = [
    "pytest>=8",
    "ruff>=0.5",
    "mypy>=1.10",
]
test = [
    "pytest-cov>=5",
    "pytest-asyncio>=0.23",
]
docs = [
    "sphinx>=7",
    "myst-parser>=3",
]
all = [
    { include-group = "test" },
    { include-group = "docs" },
]

# Group with Python version constraint
[tool.uv.dependency-groups]
typing = { requires-python = ">=3.10" }

Using Groups

# Default behavior (includes default-groups)
uv sync

# Include specific group
uv sync --group test

# Multiple groups
uv sync --group test --group docs

# Exclude group
uv sync --no-group lint

# All groups
uv sync --all-groups

# Only specific group
uv sync --only-group test

Default Groups

[tool.uv]
# Single group
default-groups = ["dev"]

# Multiple groups
default-groups = ["dev", "lint"]

# All groups
default-groups = "all"

---

Optional Dependencies (Extras)

Defining Extras

[project.optional-dependencies]
api = ["fastapi>=0.100", "uvicorn>=0.23"]
database = ["sqlalchemy>=2.0", "alembic>=1.12"]
redis = ["redis>=5.0"]
all = ["my-project[api,database,redis]"]

Using Extras

# Sync with extra
uv sync --extra api

# Multiple extras
uv sync --extra api --extra database

# All extras
uv sync --all-extras

# Run with extra
uv run --extra api python app.py

---

Package Indexes

Configuring Indexes

# Default index (replaces PyPI)
[[tool.uv.index]]
url = "https://pypi.company.com/simple"
default = true

# Additional index
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

# Explicit index (only for explicitly mapped packages)
[[tool.uv.index]]
name = "private"
url = "https://private.pypi.org/simple"
explicit = true

# Map package to index
[tool.uv.sources]
torch = { index = "pytorch" }
private-pkg = { index = "private" }

Index Authentication

# Environment variable
UV_INDEX_PRIVATE_USERNAME=user
UV_INDEX_PRIVATE_PASSWORD=pass

# Or login
uv auth login https://private.pypi.org

---

Constraints and Overrides

Constraint Dependencies

Limit versions without adding as dependencies:

[tool.uv]
constraint-dependencies = [
    "grpcio<1.65",
    "protobuf<5.0",
]

Override Dependencies

Force specific versions (dangerous - use sparingly):

[tool.uv]
override-dependencies = [
    "werkzeug==2.3.0",
]

Build Constraints

Constrain build dependencies:

[tool.uv]
build-constraint-dependencies = [
    "setuptools==60.0.0",
]

---

Exporting Lock Files

Export Formats

# Requirements.txt format
uv export --format requirements-txt -o requirements.txt

# PEP 751 pylock.toml
uv export --format pylock.toml -o pylock.toml

# CycloneDX SBOM
uv export --format cyclonedx1.5 -o sbom.json

Export Options

# Without hashes
uv export --format requirements-txt --no-hashes

# Without dev dependencies
uv export --no-dev

# With specific extras
uv export --extra api

# With all extras
uv export --all-extras

---

Virtual and Non-Package Projects

Virtual Project (No Package)

For applications that won't be published:

[project]
name = "my-app"
version = "0.1.0"

[tool.uv]
package = false  # Don't treat as installable package

Unmanaged Project

Opt out of uv management:

[tool.uv]
managed = false

---

Best Practices

Version Control

# .gitignore
.venv/
__pycache__/
*.pyc
.pytest_cache/
.mypy_cache/
.ruff_cache/
dist/
*.egg-info/

# Don't ignore these:
# pyproject.toml
# uv.lock
# .python-version

Development Workflow

1. Initial setup:

   uv sync

2. Add dependencies:

   uv add requests
   uv add --dev pytest

3. Run code:

   uv run python script.py
   uv run pytest

4. Update dependencies:

   uv lock --upgrade-package requests

5. Commit changes:

   git add pyproject.toml uv.lock
   git commit -m "Update dependencies"

CI/CD

# Always use --locked in CI
uv sync --locked

# Prune cache after CI job
uv cache prune --ci

Docker

# Install dependencies first (for caching)
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-install-project

# Then copy source
COPY . .
RUN uv sync --locked

Flask Patterns Reference

Common patterns and best practices for Flask web applications.

Application Factory

# app/__init__.py
from flask import Flask

def create_app(config_name: str = "default") -> Flask:
    """Application factory."""
    app = Flask(__name__)

    # Load config
    app.config.from_object(config[config_name])

    # Initialize extensions
    db.init_app(app)

    # Register blueprints
    from app.main import main as main_blueprint
    app.register_blueprint(main_blueprint)

    from app.api import api as api_blueprint
    app.register_blueprint(api_blueprint, url_prefix="/api")

    return app

Blueprints

# app/main/__init__.py
from flask import Blueprint

main = Blueprint("main", __name__)

from app.main import routes  # noqa: E402, F401

# app/main/routes.py
from flask import render_template
from app.main import main

@main.route("/")
def index():
    return render_template("index.html")

@main.route("/about")
def about():
    return render_template("about.html")

API Patterns

JSON Responses

from flask import jsonify, request

@app.route("/api/items", methods=["GET"])
def get_items():
    items = Item.query.all()
    return jsonify([item.to_dict() for item in items])

@app.route("/api/items", methods=["POST"])
def create_item():
    data = request.get_json()
    if not data:
        return jsonify({"error": "No data provided"}), 400

    item = Item(**data)
    db.session.add(item)
    db.session.commit()

    return jsonify(item.to_dict()), 201

@app.route("/api/items/<int:item_id>", methods=["GET"])
def get_item(item_id: int):
    item = Item.query.get_or_404(item_id)
    return jsonify(item.to_dict())

Error Handling

from flask import jsonify

@app.errorhandler(404)
def not_found(error):
    return jsonify({"error": "Not found"}), 404

@app.errorhandler(500)
def internal_error(error):
    db.session.rollback()
    return jsonify({"error": "Internal server error"}), 500

Templates

Base Template

<!-- templates/base.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{% block title %}{% endblock %} - MyApp</title>
    <link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
    {% block styles %}{% endblock %}
</head>
<body>
    <nav>
        <a href="{{ url_for('main.index') }}">Home</a>
        <a href="{{ url_for('main.about') }}">About</a>
    </nav>

    <main>
        {% with messages = get_flashed_messages(with_categories=true) %}
            {% if messages %}
                {% for category, message in messages %}
                    <div class="alert alert-{{ category }}">{{ message }}</div>
                {% endfor %}
            {% endif %}
        {% endwith %}

        {% block content %}{% endblock %}
    </main>

    <script src="{{ url_for('static', filename='js/main.js') }}"></script>
    {% block scripts %}{% endblock %}
</body>
</html>

Child Template

<!-- templates/index.html -->
{% extends "base.html" %}

{% block title %}Home{% endblock %}

{% block content %}
<h1>Welcome</h1>
<p>Hello, {{ name }}!</p>

{% for item in items %}
    <div class="item">
        <h2>{{ item.title }}</h2>
        <p>{{ item.description }}</p>
    </div>
{% else %}
    <p>No items found.</p>
{% endfor %}
{% endblock %}

Forms with Flask-WTF

from flask_wtf import FlaskForm
from wtforms import StringField, TextAreaField, SubmitField
from wtforms.validators import DataRequired, Length

class ContactForm(FlaskForm):
    name = StringField("Name", validators=[DataRequired(), Length(max=100)])
    message = TextAreaField("Message", validators=[DataRequired()])
    submit = SubmitField("Send")

@app.route("/contact", methods=["GET", "POST"])
def contact():
    form = ContactForm()
    if form.validate_on_submit():
        # Process form
        flash("Message sent!", "success")
        return redirect(url_for("main.index"))
    return render_template("contact.html", form=form)

Database with Flask-SQLAlchemy

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    posts = db.relationship("Post", backref="author", lazy=True)

    def to_dict(self) -> dict:
        return {
            "id": self.id,
            "username": self.username,
            "email": self.email,
        }

class Post(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(200), nullable=False)
    content = db.Column(db.Text, nullable=False)
    user_id = db.Column(db.Integer, db.ForeignKey("user.id"), nullable=False)

Configuration

# config.py
import os

class Config:
    SECRET_KEY = os.environ.get("SECRET_KEY") or "dev-key-change-in-prod"
    SQLALCHEMY_TRACK_MODIFICATIONS = False

class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///dev.db"

class ProductionConfig(Config):
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")

config = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "default": DevelopmentConfig,
}

Testing

# tests/conftest.py
import pytest
from app import create_app, db

@pytest.fixture
def app():
    app = create_app("testing")
    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()

@pytest.fixture
def client(app):
    return app.test_client()

# tests/test_routes.py
def test_index(client):
    response = client.get("/")
    assert response.status_code == 200

def test_api_items(client):
    response = client.get("/api/items")
    assert response.status_code == 200
    assert response.json == []

Deployment

Gunicorn

# Install
uv add gunicorn

# Run
uv run gunicorn -w 4 -b 0.0.0.0:8000 "app:create_app()"

Docker

FROM python:3.12-slim

WORKDIR /app

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

# Copy project
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .

EXPOSE 8000
CMD ["uv", "run", "gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:create_app()"]

uv Command Reference

Complete reference for uv (astral-sh/uv) Python package manager.

Installation

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

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

# Update uv
uv self update

Project Management

# Initialize
uv init <name>                    # Create new project
uv init --lib <name>              # Create library project
uv init --app <name>              # Create application project

# Dependencies
uv add <package>                  # Add dependency
uv add <package>==1.0.0           # Add specific version
uv add <package>>=1.0,<2.0        # Add version range
uv add --dev <package>            # Add dev dependency
uv add --optional <group> <pkg>   # Add optional dependency
uv remove <package>               # Remove dependency

# Sync & Lock
uv lock                           # Generate/update lockfile
uv sync                           # Sync environment with lockfile
uv sync --frozen                  # Sync without updating lock
uv sync --all-extras              # Include all optional deps

Running Code

# Run commands in project environment
uv run python script.py           # Run Python script
uv run pytest                     # Run pytest
uv run flask run                  # Run Flask
uv run <any-command>              # Run any command

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

Tools (pipx replacement)

# Run tools ephemerally
uvx ruff check .                  # Run ruff without installing
uvx black .                       # Run black formatter
uvx --from package tool           # Run tool from package

# Install tools globally
uv tool install ruff              # Install tool
uv tool upgrade ruff              # Upgrade tool
uv tool uninstall ruff            # Remove tool
uv tool list                      # List installed tools

Python Version Management

# Install Python versions
uv python install 3.12            # Install specific version
uv python install 3.11 3.12       # Install multiple versions
uv python list                    # List available versions
uv python list --installed        # List installed versions

# Pin version for project
uv python pin 3.12                # Creates .python-version file

# Create venv with specific version
uv venv --python 3.12

Virtual Environments

# Create venv
uv venv                           # Create .venv
uv venv myenv                     # Create named venv
uv venv --python 3.12             # With specific Python

# Activate (standard way)
source .venv/bin/activate         # Linux/macOS
.venv\Scripts\activate            # Windows

pip Interface (drop-in replacement)

# Install packages
uv pip install <package>
uv pip install -r requirements.txt
uv pip install -e .               # Editable install

# Compile requirements
uv pip compile requirements.in -o requirements.txt
uv pip compile --universal        # Platform-independent

# Sync environment
uv pip sync requirements.txt

# Other pip commands
uv pip list
uv pip show <package>
uv pip freeze
uv pip uninstall <package>

Scripts with Inline Dependencies

# Add dependencies to script
uv add --script script.py requests pandas

# Run script (auto-installs deps)
uv run script.py

Script format:

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests>=2.31",
#     "pandas>=2.0",
# ]
# ///

import requests
import pandas as pd
# ...

Build & Publish

# Build package
uv build                          # Build sdist and wheel
uv build --sdist                  # Build source dist only
uv build --wheel                  # Build wheel only

# Publish to PyPI
uv publish                        # Publish to PyPI
uv publish --token <token>        # With API token

Configuration

pyproject.toml

[project]
name = "my-package"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "flask>=3.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0",
]

Environment Variables

UV_CACHE_DIR          # Cache directory location
UV_NO_CACHE           # Disable cache
UV_PYTHON             # Default Python version
UV_SYSTEM_PYTHON      # Use system Python
UV_COMPILE_BYTECODE   # Compile .pyc files

Python Project Skill

Modern Python project development using uv package manager and Flask for web components.

Quick Start

New Project with uv

# Initialize new project
uv init my-project
cd my-project

# Add dependencies
uv add flask pytest ruff mypy

# Run application
uv run python app.py

# Run with Flask
uv run flask run --debug

Package Manager: uv

Use uv (astral-sh/uv) for all Python package management. It replaces pip, poetry, pyenv, and virtualenv.

Common Commands

# Project management
uv init <name>              # Initialize project
uv add <package>            # Add dependency
uv remove <package>         # Remove dependency
uv sync                     # Sync dependencies from lockfile
uv lock                     # Generate lockfile

# Running
uv run <command>            # Run in project environment
uv run python script.py     # Run Python script
uv run pytest               # Run tests

# Tools (like pipx)
uvx <tool>                  # Run tool in ephemeral env
uv tool install <tool>      # Install tool globally

# Python versions
uv python install 3.12      # Install Python version
uv python pin 3.12          # Pin version for project

Web Framework: Flask

Use Flask for web applications - lightweight WSGI micro-framework.

Minimal Flask App

# app.py
from flask import Flask, render_template, request, jsonify

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/data", methods=["GET", "POST"])
def api_data():
    if request.method == "POST":
        data = request.get_json()
        return jsonify({"status": "ok", "received": data})
    return jsonify({"message": "Hello, API!"})

if __name__ == "__main__":
    app.run(debug=True)

Flask Project Structure

my_flask_app/
├── app.py                  # Application entry
├── pyproject.toml          # uv project config
├── static/                 # CSS, JS, images
│   ├── css/
│   └── js/
├── templates/              # Jinja2 templates
│   ├── base.html
│   └── index.html
└── tests/
    └── test_app.py

Run Flask

# Development
uv run flask run --debug

# With specific host/port
uv run flask run --host=0.0.0.0 --port=8080

Project Configuration

pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.11"
dependencies = [
    "flask>=3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.5",
    "mypy>=1.10",
]

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

[tool.mypy]
python_version = "3.11"
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]

Code Quality

# Linting and formatting with ruff
uv run ruff check .          # Check for issues
uv run ruff check . --fix    # Auto-fix issues
uv run ruff format .         # Format code

# Type checking
uv run mypy .

# Testing
uv run pytest
uv run pytest -v --cov=src

Scripts

• scripts/init-project.sh - Initialize new Python project with standard structure
• scripts/setup-flask.sh - Set up Flask application boilerplate

References

• See references/uv-commands.md for complete uv reference
• See references/flask-patterns.md for Flask best practices

uv Python Version Management Reference

Comprehensive guide to managing Python versions with uv.

Overview

uv provides integrated Python version management:

• Automatic Python downloads when needed
• Multiple version installations
• Version pinning per project or globally
• Support for CPython, PyPy, GraalPy, and Pyodide

---

Installing Python

Basic Installation

# Install latest Python
uv python install

# Install specific version
uv python install 3.12
uv python install 3.12.5

# Install multiple versions
uv python install 3.11 3.12 3.13

# Install with default executables (python, python3)
uv python install 3.12 --default

Alternative Implementations

# PyPy
uv python install pypy
uv python install pypy@3.10

# GraalPy
uv python install graalpy

# Specific implementation version
uv python install cpython@3.12

Version Constraints

# Range constraint
uv python install ">=3.11,<3.13"

# Latest satisfying constraint
uv python install ">=3.10"

Installation Options

# Reinstall existing versions
uv python install --reinstall

# Include preview releases
uv python install --preview

---

Listing Python Versions

Basic Listing

# Show available and installed versions
uv python list

# Filter by version
uv python list 3.12
uv python list pypy

# Show only installed
uv python list --only-installed

Advanced Listing

# Include all patch versions
uv python list --all-versions

# Show downloads for all platforms
uv python list --all-platforms

Output Example

cpython-3.13.1-macos-aarch64-none     # installed
cpython-3.12.8-macos-aarch64-none     # installed
cpython-3.12.7-macos-aarch64-none     # available
cpython-3.11.10-macos-aarch64-none    # installed
pypy-3.10.14-macos-aarch64-none       # available

---

Version Pinning

Project-Level Pin

# Create .python-version in current directory
uv python pin 3.12

# Pin exact version
uv python pin 3.12.5

# Pin with resolved exact version
uv python pin 3.12 --resolved

Global Pin

# User-level default
uv python pin --global 3.12

Pin File Format

.python-version:

3.12

For multiple versions (.python-versions):

3.11
3.12
3.13

pyproject.toml Constraint

[project]
requires-python = ">=3.11"

---

Finding Python

Basic Find

# Find first available Python
uv python find

# Find specific version
uv python find 3.12
uv python find ">=3.11"

Find Options

# Ignore virtual environments
uv python find --system

# Ignore project requirements
uv python find --no-project

Discovery Order

1. Managed Python installations (UV_PYTHON_INSTALL_DIR) 2. PATH executables (python, python3, python3.x) 3. Windows registry / Microsoft Store (Windows only)

---

Version Selection

Command-Line Override

# Use specific version for any command
uv sync --python 3.12
uv run --python 3.11 python script.py
uv venv --python 3.12

Environment Variable

# Set default Python
export UV_PYTHON=3.12

Selection Priority

1. --python command-line argument 2. UV_PYTHON environment variable 3. .python-version file (searches up directory tree) 4. requires-python in pyproject.toml 5. First available Python

---

Version Request Formats

Standard Formats

Special Variants

# Free-threaded Python (3.13+)
uv python install 3.13t
uv python install 3.13+freethreaded

# Debug build
uv python install 3.13d
uv python install 3.13+debug

# Force GIL-enabled (3.14+)
uv python install 3.14+gil

Platform-Specific

# Full specification
uv python install cpython-3.12.3-macos-aarch64-none
uv python install cpython-3.12.3-linux-x86_64-gnu

---

Upgrading Python

Upgrade Command (Preview)

# Upgrade to latest patch version
uv python upgrade 3.12

# Upgrade all installed versions
uv python upgrade

Note: Only supports patch upgrades (3.12.x -> 3.12.y), not minor upgrades.

Auto-Upgrade Virtual Environments (Preview)

# Enable with preview features
uv python install 3.12 --preview-features python-upgrade

---

Uninstalling Python

# Remove specific version
uv python uninstall 3.11

# Remove multiple versions
uv python uninstall 3.11 3.12

---

Configuration

Environment Variables

Python Preference

Configure how uv selects Python:

# uv.toml or [tool.uv] in pyproject.toml
[tool.uv]
python-preference = "managed"  # default

Options:

• managed - Prefer uv-managed, fall back to system
• only-managed - Only use uv-managed versions
• system - Prefer system over managed
• only-system - Only use system versions

Disable Auto-Download

# Command-line
uv sync --no-python-downloads

# Environment variable
export UV_NO_PYTHON_DOWNLOADS=1

# Configuration file
[tool.uv]
python-downloads = "manual"

---

Supported Implementations

CPython (Default)

• Source: Astral's python-build-standalone
• Self-contained, portable, performant
• Aliases: cpython, cp

PyPy

• Source: PyPy project official distributions
• JIT-compiled Python
• Aliases: pypy, pp

GraalPy

• Source: GraalPy project distributions
• Aliases: graalpy, gp

Pyodide

• WebAssembly Python
• Alias: pyodide

---

Platform Support

Supported Platforms

Transparent Emulation

On macOS (aarch64) with Rosetta 2:

• Both x86_64 and aarch64 binaries work
• uv can use either, packages must match architecture

On Windows (ARM) with WoA:

• x86_64 binaries work via emulation
• Same architectural consistency requirement

---

Windows Integration

Registry Integration

uv automatically registers managed Python in Windows registry (PEP 514):

• Enables discovery by py launcher
• Enables discovery by other tools

Using py Launcher

py -V:Astral/CPython3.13.1

---

Common Workflows

Multi-Version Testing

# Install multiple versions
uv python install 3.10 3.11 3.12 3.13

# Test against each
for v in 3.10 3.11 3.12 3.13; do
  uv run --python $v pytest
done

Project with Specific Version

# Pin version
uv python pin 3.12

# Sync will use pinned version
uv sync

# Run uses pinned version
uv run python --version

Isolated Tool Execution

# Run tool with specific Python
uvx --python 3.11 ruff check .

# Install tool with specific Python
uv tool install --python 3.12 mypy

CI/CD Configuration

# GitHub Actions
- uses: astral-sh/setup-uv@v7
  with:
    python-version: "3.12"

# Or use matrix
strategy:
  matrix:
    python-version: ["3.10", "3.11", "3.12"]
steps:
  - uses: astral-sh/setup-uv@v7
    with:
      python-version: ${{ matrix.python-version }}

---

Troubleshooting

Version Not Found

# Check available versions
uv python list --all-versions

# Check if installed
uv python list --only-installed

# Force download
uv python install 3.12

Wrong Version Selected

# Check what's being used
uv python find

# Explicitly specify
uv run --python 3.12 python --version

# Check .python-version
cat .python-version

# Check pyproject.toml
grep requires-python pyproject.toml

Virtual Environment Issues

# Recreate with specific version
rm -rf .venv
uv venv --python 3.12
uv sync

System Python Conflicts

# Use only managed Python
export UV_MANAGED_PYTHON=1

# Or configure
[tool.uv]
python-preference = "only-managed"