Python Cheatsheet 06 — uv Packaging and Workflow

curl -LsSf https://astral.sh/uv/install.sh | sh
# or
brew install uv

uv init myapp
cd myapp

uv add fastapi pydantic sqlalchemy[asyncio]
uv add --dev pytest pytest-anyio httpx ruff mypy
uv add 'pydantic>=2.5,<3'
uv add 'requests; python_version < "3.13"'
uv add -e ../my-other-package          # editable
uv add git+https://github.com/x/y.git

uv remove requests

uv sync                       # all deps from uv.lock
uv sync --frozen              # error if lock would change (CI)
uv sync --no-dev              # skip dev deps
uv sync --group docs          # specific group

uv lock                       # regenerate uv.lock
uv lock --upgrade             # upgrade all
uv lock --upgrade-package pydantic

uv run python main.py
uv run pytest
uv run ruff check
uv run --with httpx python script.py     # one-off dep

uv python list
uv python install 3.13
uv python pin 3.13           # writes .python-version
uv python find

uv tool install ruff
uv tool install black
uv tool install ipython
uv tool list
uv tool upgrade --all
uv tool run pytest           # without installing

uvx pytest                   # tool run
uvx --with httpx python -c "import httpx; print(httpx.__version__)"

[project]
name = "myapp"
version = "0.1.0"
description = "..."
authors = [{name = "Me"}]
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.115",
    "pydantic>=2.9",
]

[dependency-groups]
dev = ["pytest", "ruff"]
docs = ["mkdocs", "mkdocs-material"]

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

[tool.uv]
package = true            # treats project as installable

[tool.uv.workspace]
members = ["packages/*", "apps/*"]

[tool.uv.sources]
mypackage = { git = "https://github.com/me/mypackage", rev = "main" }
local-pkg = { path = "../local-pkg" }

uv build                     # creates dist/*.whl + *.tar.gz
uv build --sdist
uv build --wheel

uv publish                   # to PyPI
uv publish --index test-pypi

uv cache dir
uv cache clean
uv cache prune --ci          # CI-friendly prune

uv pip install requests       # like pip install
uv pip list
uv pip freeze
uv pip uninstall requests

3.13

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = ["httpx", "rich"]
# ///

import httpx
from rich import print
print(httpx.get("https://example.com").status_code)

uv run script.py

- uses: astral-sh/setup-uv@v3
- run: uv sync --frozen
- run: uv run pytest

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

# Bootstrap new project
uv init myapp && cd myapp
uv add fastapi 'pydantic[email]>=2.5'
uv add --dev pytest pytest-anyio httpx ruff mypy
uv run uvicorn src.myapp.main:app --reload

# Run formatter / linter
uv run ruff format .
uv run ruff check . --fix
uv run mypy src

# Update one dep
uv add 'pydantic>=2.10'
uv sync