Cookiecutter FastAPI Starter

A pragmatic, production-minded FastAPI project generator, inspired by cookiecutter-django.

It generates a project with:

• FastAPI application factory
• Versioned API routes (/api/v1)
• Settings via pydantic-settings
• SQLAlchemy 2.0 session management
• Alembic migrations
• Optional JWT authentication
• A single, consistent API error envelope
• Request ID middleware
• Structured logging
• Health check endpoint
• Pytest test setup
• GitHub Actions CI
• Optional pre-commit hooks
• Optional Docker and Docker Compose files
• Optional Ruff and mypy configuration

Install

pip install cookiecutter-fastapi-starter

Usage

cookiecutter-fastapi-starter

Answer the prompts and you get a runnable project. To skip the prompts and override individual values:

cookiecutter-fastapi-starter --no-input -o ./projects include_auth=no database=sqlite

--help lists the flags. If you already use Cookiecutter, you can skip the install entirely and point it at the repository:

cookiecutter gh:pratik16102001/cookiecutter-fastapi

Running the generated project

cd my-fastapi-app
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
alembic upgrade head
uvicorn app.main:app --reload

• API: http://localhost:8000
• Interactive docs: http://localhost:8000/docs (disabled when ENVIRONMENT=production)
• Health: http://localhost:8000/api/v1/health

Template options

Generated layout

my-fastapi-app/
├── app/
│   ├── api/v1/            # Router and route modules
│   ├── core/              # Config, logging, errors, security
│   ├── db/                # Declarative base and session factory
│   ├── middleware/        # Request ID middleware
│   ├── models/            # SQLAlchemy models
│   ├── schemas/           # Pydantic schemas
│   ├── services/          # Business logic and data access
│   └── main.py            # Application factory
├── alembic/               # Migration environment and versions
├── tests/
└── pyproject.toml

Every error response uses one shape, carrying the request ID so that a client report can be traced to a log line:

{ "error": { "code": "http_error", "message": "Not Found", "request_id": "..." } }

Before you deploy a generated project

The defaults are tuned for local development. Change these first:

• Set a real SECRET_KEY in .env.
• Set ENVIRONMENT=production (this also disables /docs and /redoc).
• Narrow allowed_hosts from ["*"] to your actual hostnames.
• Narrow CORS_ORIGINS to your real front-end origins.

Contributing

See CONTRIBUTING.md and our Code of Conduct. To report a security issue, see SECURITY.md.

Roadmap

• Role-based access control
• Redis cache option
• Celery/RQ background jobs
• OpenAPI client generation
• Kubernetes deployment examples

License

MIT — see LICENSE.