Learn how to customize templates to fit your specific needs
Templates provided by create-awesome-python-app are designed to be customizable. This guide shows how to adapt generated Python projects — from project layout and tooling configuration to dependencies and environment settings.
After scaffolding, reorganize modules to match your domain. Common patterns across CPA templates:
Group routers, services, and schemas by feature (e.g. src/users/, src/billing/).
Keep cross-cutting code in src/core/ or packages/common/ for workspace templates.
Centralize configuration with pydantic-settings; extend the generated settings class rather than scattering env reads.
Place tests under tests/ mirroring the package layout for easier navigation.
Templates ship with uv, Ruff, pytest, and type-checker defaults you can tune:
[project] name = "my-app" requires-python = ">=3.12" dependencies = [ "fastapi>=0.115", "uvicorn[standard]>=0.32", ] [dependency-groups] dev = [ "pytest>=8.0", "ruff>=0.8", "mypy>=1.13", ] [tool.uv] dev-dependencies = []
Adjust Python version bounds, add runtime deps with uv add, and extend dev tooling in [dependency-groups].
Manage dependencies with uv after scaffolding:
# Add a runtime dependency uv add httpx # Add a dev dependency uv add --dev pytest-asyncio # Update the lockfile after manual pyproject edits uv sync # Remove a dependency uv remove unused-package
After adding packages that need app wiring (ORM, Redis, Sentry), follow the extension or template docs for initialization hooks.
If you want extensions on an existing project, you can manually port the files from cpa-templates/extensions or re-scaffold with the desired combination:
pyproject.toml fragments, then run uv sync.Different CPA templates have distinct extension points:
fastapi-sqlalchemy or fastapi-auth-jwt when needed.Settings class for new env vars.fastapi-sentry during scaffold or wire Sentry manually in lifespan hooks.# app/main.py (simplified) from fastapi import FastAPI from app.api.routes import health, users app = FastAPI(title="my-app") app.include_router(health.router, prefix="/health", tags=["health"]) app.include_router(users.router, prefix="/users", tags=["users"])
For deeper changes, adjust runtime configuration and deployment artifacts:
Use .env locally (never commit secrets) and typed settings in code:
# .env.example APP_ENV=development DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/app SENTRY_DSN=
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", extra="ignore")
app_env: str = "development"
database_url: strWhen you scaffold with fastapi-docker, customize Dockerfile, compose.yml, and health checks for your deployment target. Rebuild with docker compose up --build after changes.