Packages & libraries

curl -LsSf https://astral.sh/uv/install.sh | sh  # or:
brew install uv
uv self update                 # standalone installs only

uv python install 3.14         # managed CPython
uv python install 3.14t        # free-threaded (no GIL) build
uv python install --default    # python, python3 on PATH
uv python pin 3.14             # writes .python-version
uv python list --only-installed
uv python upgrade 3.14         # latest patch release
uv run -p 3.13 pytest          # one run on another version

uv init shop                   # packaged app, src/ layout
uv init --lib shop             # library (adds py.typed)
uv init --no-package scripts   # flat main.py, no build
cd shop
uv add httpx "pydantic>=2.11"  # [project] dependencies
uv add --dev pytest ruff       # dependency group "dev"
uv add --group docs mkdocs     # another group
uv add --optional cli typer    # extra: pip install shop[cli]
uv add "git+https://github.com/org/lib@v1.2.0"
uv add --editable ../shared    # local path dependency
uv add -r requirements.txt     # import an old project
uv remove httpx
uv lock --upgrade-package httpx  # bump one dep in the lock
uv lock --upgrade              # bump everything allowed
uv sync --locked               # CI: fail if lock is stale
uv run python -m shop
uv run --with rich python      # extra package, this run only
uv run --env-file .env uvicorn app:app

uvx ruff check .               # run a tool in a cached env
uvx ruff@0.16.9 check .        # a specific version
uvx --from httpie http GET example.com  # package ≠ command
uv tool install ruff           # put ruff on PATH for good
uv tool list
uv tool upgrade --all
uv tool install -e .           # your own CLI, editable

uv init --script tool.py --python 3.14
uv add --script tool.py httpx rich  # edits the header
uv run tool.py
uv lock --script tool.py           # tool.py.lock beside it

[project]
name = "shop"              # PyPI name; import name is shop
version = "0.1.0"
description = "Carts and invoices"
readme = "README.md"
requires-python = ">=3.14"
license = "MIT"            # SPDX expression
authors = [{ name = "Ada", email = "ada@example.com" }]
dependencies = [
  "httpx>=0.28",
  "pydantic>=2.11,<3",
  "uvloop>=0.21; sys_platform != 'win32'",  # marker
]
 
[project.optional-dependencies]  # extras: shop[cli]
cli = ["typer>=0.27"]
 
[project.scripts]          # console commands
shop = "shop.cli:app"
 
[project.entry-points."pytest11"]  # plugin hooks
shop = "shop.pytest_plugin"
 
[project.urls]
Homepage = "https://github.com/acme/shop"
 
[dependency-groups]        # dev-only, never published
dev = ["pytest>=9", "ruff>=0.16"]
docs = ["mkdocs-material>=9"]
ci = [{ include-group = "dev" }, "pytest-cov>=7"]
 
[build-system]
requires = ["uv_build>=0.12.19,<0.13"]
build-backend = "uv_build"
 
[tool.uv]
default-groups = ["dev", "docs"]  # synced by default

"""Public API: callers import from shop, not submodules."""
 
from shop.cart import Cart, Line
 
__all__ = ["Cart", "Line"]  # what `from shop import *` gets

from shop.cart import Cart  # absolute: the default choice
 
from ..cart import Line  # relative: up one package
from .errors import PaymentError  # same package
 
 
def charge(cart: Cart) -> Line:
    if not cart.lines:
        raise PaymentError("empty cart")
    return cart.lines[-1]

import sys
 
from shop.cli import main
 
sys.exit(main())

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

[project]
name = "api"
dependencies = ["core"]
 
[tool.uv.sources]
core = { workspace = true }  # use the local member

uv init apps/api               # joins the workspace
uv add --package api core      # writes both lines above
uv sync --all-packages
uv run --package api pytest
uv workspace list

uv build                       # dist/*.tar.gz + *.whl
uv build --package core        # one workspace member
uv version --bump patch
uv publish                     # token or trusted publishing
uv publish --index testpypi    # index with publish-url

name: release
on:
  push:
    tags: ["v*"]
jobs:
  pypi:
    runs-on: ubuntu-latest
    environment: pypi
    permissions:
      id-token: write  # OIDC token for PyPI
      contents: read
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
      - run: uv build
      - run: uv publish  # detects trusted publishing

[tool.ruff]
line-length = 88  # target-version from requires-python
 
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
 
[tool.mypy]
strict = true
files = ["src", "tests"]
 
[tool.pyright]
typeCheckingMode = "strict"
 
[tool.ty.rules]
possibly-unresolved-reference = "error"

uv init --app shop --python 3.14
cd shop
uv add fastapi uvicorn pydantic-settings
uv add --dev pytest ruff mypy
# write src/shop/main.py with app = FastAPI()
uv run uvicorn shop.main:app --reload
git add pyproject.toml uv.lock .python-version

uv init --lib acme-geo         # import name: acme_geo
cd acme-geo
uv add "httpx>=0.28"           # keep lower bounds loose
uv add --dev pytest mypy ruff
uv run pytest && uv run mypy src
uv build && ls dist

[project.scripts]
acme = "acme_cli.cli:app"  # module:callable

from typing import Annotated
 
import typer
 
app = typer.Typer(no_args_is_help=True)
 
 
@app.command()
def greet(
    name: str,
    shout: Annotated[bool, typer.Option("--shout")] = False,
) -> None:
    """Say hello."""
    msg = f"Hello, {name}!"
    typer.echo(msg.upper() if shout else msg)
 
 
@app.command()
def version() -> None:
    typer.echo("0.1.0")

uv python pin 3.14             # .python-version, commit it
# pyproject.toml: requires-python = ">=3.14"
uv sync                        # rebuilds .venv on 3.14
uv run python --version
uv python pin --global 3.14    # default outside projects

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.14"
# dependencies = ["httpx>=0.28", "rich>=14"]
# [tool.uv]
# exclude-newer = "2026-09-01T00:00:00Z"
# ///
import sys
 
import httpx
from rich import print
 
 
def stars(repo: str) -> int:
    url = f"https://api.github.com/repos/{repo}"
    r = httpx.get(url, timeout=10)
    r.raise_for_status()
    return int(r.json()["stargazers_count"])
 
 
if __name__ == "__main__":
    repo = sys.argv[1] if sys.argv[1:] else "astral-sh/uv"
    print(f"[bold]{repo}[/]: {stars(repo):,} stars")

[[tool.uv.index]]
name = "internal"
url = "https://pkgs.example.com/simple/"
explicit = true  # only for packages pinned below
 
[tool.uv.sources]
acme-auth = { index = "internal" }

export UV_INDEX_INTERNAL_USERNAME=ci
export UV_INDEX_INTERNAL_PASSWORD="$TOKEN"
uv add acme-auth

name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.13", "3.14"]
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          python-version: ${{ matrix.python }}
      - run: uv sync --locked --all-extras
      - run: uv run ruff check
      - run: uv run pytest