Installation

Requirements

Python 3.11 or higher
uv (recommended) or pip

Quick start

# uv (recommended — fast, deterministic)
uv add quadkit-cli

# pip
pip install quadkit-cli

quadkit --version
quadkit new project my-app --template web-api
cd my-app
quadkit run

That is the whole install. Open http://127.0.0.1:8000/docs for OpenAPI. The walkthrough is Your First App.

The core quadkit package (Application, Provider, Container, Result, modules, YAML config) is pulled in by the CLI and by every extension. quadkit-contracts installs automatically.

Pin the alpha line when you ship:

uv add "quadkit-cli>=0.0.42,<0.1"

If quadkit is not on PATH after uv add, run it as uv run quadkit.

Templates

quadkit new project always writes one tree. The template only changes which packages and application.yaml sections land — not the shape of src/.

Template	What it adds
`minimal`	Core only
`api`	JSON API (`quadkit-web`)
`web-api` (default)	Web API with OpenAPI

The CLI only offers templates whose providers are installed, so a public install shows exactly these three. Templates that need persistence, queues, or auth (graphql, worker, full) are listed by quadkit new project --help only when their packages are present.

There is no --structure flag. Feature types live in domains/. App providers live in app-root di/. See Project Structure.

Add packages later

Install only what you need. Every extension depends only on quadkit and quadkit-contracts — never on each other.

quadkit add web                    # quadkit-web + web: section in application.yaml
quadkit add testing                # quadkit-testing (test harnesses)

uv add quadkit-web                 # ASGI, controllers, OpenAPI
uv add --dev quadkit-testing       # fakes, test beds, compliance suites

quadkit add patches pyproject.toml (via uv add when available) and writes the provider’s default block into application.yaml. It only offers providers whose distribution is installed — on a public install that is whichever of the published packages you have added (web, testing, sql, cache, storage, events, tasks, monitor, auth, http). The catalog is thirteen packages; see The Ecosystem.

Without the CLI

You can compose an app by hand with uv add quadkit quadkit-web and a create_app() factory. The CLI is still the supported path — it lays down the one project tree that generators and quadkit run expect.

Verify

quadkit --version
python -c "import quadkit; print(quadkit.__version__)"
quadkit run

You should see OpenAPI at /docs. That is the “it works” check.

Next Steps

Your First App — scaffold, run, add a route
For coding agents — read order, repo map, recipes
Agent skills — Claude Code, Cursor, OpenCode pack
Common mistakes — fail vs fix
Project Structure — the tree the CLI writes
The Ecosystem — the published packages, grouped by purpose