# Python Quick Start (/docs/guides/python-quick-start)



## Overview [#overview]

This guide walks through the default TriStack flow: scaffold a FastAPI + SQLModel + Alembic + SQLite project, run it, and verify the health endpoint.

## Install the CLI [#install-the-cli]

Python projects run the CLI as `uvx tristack`. If you don't use `uv`, install the standalone binary instead:

<CodeBlockTabs defaultValue="python">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="python">
      Python (any OS)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="windows">
      Windows
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="macos">
      macOS
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="linux">
      Linux
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="python">
    ```bash
    # run on demand — no install needed
    uvx tristack

    # or install once with uv
    uv tool install tristack
    ```
  </CodeBlockTab>

  <CodeBlockTab value="windows">
    `powershell irm https://tristack.space/install.ps1 | iex `
  </CodeBlockTab>

  <CodeBlockTab value="macos">
    `bash curl -fsSL https://tristack.space/install.sh | bash `
  </CodeBlockTab>

  <CodeBlockTab value="linux">
    ```bash
    curl -fsSL https://tristack.space/install.sh | bash
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 1. Scaffold [#1-scaffold]

```bash
uvx tristack my-api
```

Follow the prompts, or skip them and take the defaults completely non-interactively:

```bash
uvx tristack my-api --yes
```

After scaffolding you'll see the reproducible command, which is also saved to `tristack.jsonc` inside the project.

## 2. Run it [#2-run-it]

```bash
cd my-api
cp .env.example .env
uv sync
uv run uvicorn src.main:app --reload
```

Open `http://localhost:8000/health` — you should see `{"status":"ok"}`.

<Callout title="Note">
  The import package is a fixed `src/` directory — the project name never appears inside the tree.
  The distribution/project name in `pyproject.toml` is still your snake\_case project name (`my_api`
  for `my-api`). The health endpoint, database URLs, and docs all follow from your selections.
</Callout>

## 3. Common commands [#3-common-commands]

```bash
uv sync                # install dependencies (default package manager)
uv add <package>       # add a dependency
uv run pytest          # run the test suite (pytest addon)
uv run ruff check .    # lint (ruff addon)
uv run ruff format .   # format (ruff addon)
uv run mypy .          # type-check (mypy addon)
```

### Database migrations [#database-migrations]

With Alembic, migrations live in `migrations/`:

```bash
uv run alembic revision --autogenerate -m "create users"
uv run alembic upgrade head
```

### Docker [#docker]

With the `docker` addon, run the whole stack in containers:

```bash
docker compose up --build
```

## 4. Other frameworks [#4-other-frameworks]

The stack varies by framework — same flow, different runner:

| Framework         | Scaffold flag          | Run                                                      |
| ----------------- | ---------------------- | -------------------------------------------------------- |
| FastAPI (default) | `--framework fastapi`  | `uv run uvicorn src.main:app --reload`                   |
| Litestar          | `--framework litestar` | `uv run litestar run --reload`                           |
| Flask             | `--framework flask`    | `uv run flask --app src.main run --debug`                |
| Django            | `--framework django`   | `uv run manage.py migrate && uv run manage.py runserver` |

## 5. Reproduce the same stack [#5-reproduce-the-same-stack]

Every scaffold prints a reproducible command and stores it in `tristack.jsonc`:

```bash
uvx tristack my-api \
  --language python \
  --framework fastapi \
  --orm sqlmodel \
  --migrations alembic \
  --database sqlite \
  --package-manager uv \
  --addons docker ruff pytest
```

Or validate it without writing anything:

```bash
uvx tristack my-api --yes --dry-run
```

## Next steps [#next-steps]

* [Project Structure](/docs/project-structure) — exactly what gets generated
* [CLI Options](/docs/cli/options) — every flag
* [Compatibility](/docs/cli/compatibility) — valid combinations