cookiecutter-python-fastapi-template

A Cookiecutter template for production-ready FastAPI services — managed with uv and ready to ship with Docker and Docker Compose.

Every generated project comes with:

• clean FastAPI app (src/ layout, settings via pydantic-settings, CORS, lifespan hooks, health/readiness probes)
• multi-stage Dockerfile (uv builder → slim runtime, non-root user)
• docker-compose.yml with a healthchecked API service (and an optional PostgreSQL service)
• .env.example driving all configuration
• scripts/build.sh and scripts/deploy.sh to build & deploy the stack
• pytest tests, ruff config, and a Makefile of shortcuts

Usage

You'll be prompted to enter values. Then it creates your project in the current working directory based on those answers. No local install needed — run it with uvx (or pipx run / pip install cookiecutter):

uvx cookiecutter gh:Kurdzik/cookiecutter-python-fastapi-template

You can also point Cookiecutter at a local checkout:

uvx cookiecutter path/to/cookiecutter-python-fastapi-template

Then:

cd my-fastapi-service
cp .env.example .env
./scripts/build.sh
./scripts/deploy.sh          # -> http://localhost:8000/docs

Prompts

Variable	Description	Default
project_name	Human-readable name	My FastAPI Service
project_slug	Directory / repo name (kebab-case)	derived from project_name
package_name	Importable Python package (snake_case)	derived from project_slug
project_description	Short description	—
author_name	Author name (also used in the MIT LICENSE)	Your Name
author_email	Author email	you@example.com
version	Initial version	0.1.0
python_version	Python version for the app and Docker images	3.12
app_port	Port the API listens on	8000
use_postgres	Add a PostgreSQL service + async SQLAlchemy	yes

Generated layout

my-fastapi-service/
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── Makefile
├── pyproject.toml
├── scripts/
│   ├── build.sh
│   └── deploy.sh
├── src/
│   └── my_fastapi_service/
│       ├── main.py
│       ├── config.py
│       ├── db.py            # only when use_postgres = yes
│       └── api/
│           ├── router.py
│           └── routes/health.py
└── tests/

Developing this template

The template ships with a bake test using pytest-cookies:

uv sync
uv run pytest

License

MIT — see LICENSE.