Create Awesome Python App

One command. Any stack. Generate production-ready Python apps by composing templates, addons, and AI-ready conventions.

From blank folder to a working FastAPI, Django, Celery, CLI, or uv workspace project with modern tooling and team-friendly automation.

Official Site · Templates · Extensions · Docs · GitHub · PyPI

Install

uv (recommended):

uvx create-awesome-python-app@latest my-app

pipx:

pipx run create-awesome-python-app my-app

Homebrew (macOS / Linux):

brew tap Create-Python-App/tap
brew install create-awesome-python-app

AUR (Arch Linux):

yay -S create-awesome-python-app   # or: paru -S create-awesome-python-app

Docker:

docker run --rm -it -v "${PWD}:/app" -w /app \
  ulisesjeremias/create-awesome-python-app:latest my-app \
  --template fastapi-starter

Interactive by default outside CI. For automation, run headless with flags:

uvx create-awesome-python-app my-api \
  --template fastapi-starter \
  --addons github-setup \
  --addons fastapi-sqlalchemy \
  --no-interactive

Shell completion

create-awesome-python-app --install-completion   # bash / zsh / fish
create-awesome-python-app --show-completion      # print script only

After installing, restart the shell (or source your profile) and tab-complete flags such as --template, --addons, and cache subcommands.

Why CPA?

Composition Model

template -> addons -> custom options -> install -> git init -> AI-ready project

You can mix catalog templates and addons with your own GitHub or file:// sources.

What You Can Generate

Template Families

Addon Families

Browse the live catalog on the official site or in cpa-templates.

Popular Recipes

FastAPI + GitHub + SQLAlchemy

uvx create-awesome-python-app my-api \
  --template fastapi-starter \
  --addons github-setup \
  --addons fastapi-sqlalchemy \
  --no-interactive

Django API + Postgres + Docker

uvx create-awesome-python-app my-django \
  --template django-api \
  --addons github-setup \
  --addons postgres \
  --addons django-docker \
  --no-interactive

Celery worker + Redis-friendly stack

uvx create-awesome-python-app my-worker \
  --template celery-worker \
  --addons github-setup \
  --addons celery-docker \
  --no-interactive

Typer / Click CLI starter

uvx create-awesome-python-app my-cli \
  --template cli-starter \
  --addons github-setup \
  --no-interactive

uv workspace monorepo

uvx create-awesome-python-app my-workspace \
  --template uv-workspace-starter \
  --addons github-setup \
  --no-interactive

Internal platform template (GitHub URL)

uvx create-awesome-python-app my-internal-app \
  --template "https://github.com/your-org/platform-starters?subdir=templates/internal-app" \
  --no-interactive

Local template development (file://)

uvx create-awesome-python-app my-local-app \
  --template "file:///absolute/path/to/cpa-templates?subdir=templates/fastapi-starter" \
  --no-interactive

file:// template URLs should be absolute paths (for example file:///Users/... or file:///home/...).

Layer a private extension

uvx create-awesome-python-app my-app \
  --template fastapi-starter \
  --addons github-setup \
  --extend "https://github.com/your-org/platform-starters?subdir=extensions/company-ci"

Pass custom template values

uvx create-awesome-python-app my-app \
  --template fastapi-starter \
  --set "productName=Acme Cloud" \
  --set "author=Platform Team" \
  --no-interactive

Built For Modern Teams

• Python 3.12+ runtime support.
• uv-first workflows (with pipx / Homebrew / AUR / Docker install paths).
• Interactive wizard for local workflows.
• --no-interactive mode for CI, scripts, and platform automation.
• GitHub URL and local file:// template inputs.
• --extend support for private addon layering.
• --set key=value overrides for deterministic custom options.

Explore The Catalog

Browse visually at create-awesome-python-app.vercel.app or discover from the terminal:

# List all available templates
uvx create-awesome-python-app --list-templates

# List addons (optionally filtered by template)
uvx create-awesome-python-app --template fastapi-starter --list-addons

Full catalog:

• Templates: create-awesome-python-app.vercel.app/templates
• Extensions: create-awesome-python-app.vercel.app/extensions
• Source data: cpa-templates/templates.json

Override the catalog URL with CPA_CATALOG_URL (HTTPS or file://) for forks and local testing.

AI-Ready With AGENTS.md

Supported templates generate an AGENTS.md file so coding assistants understand project context before editing:

Interactive Wizard

Run the CLI without flags and CPA guides you through:

Requirements

• Python >= 3.12
• uv recommended (or pipx / Homebrew / AUR / Docker)
• git available on PATH (required to clone templates)

Recommended quick start:

uv python install 3.12
uvx create-awesome-python-app@latest my-app

CLI Reference

Usage: create-awesome-python-app [OPTIONS] [project_directory]

cache subcommand

Usage: create-awesome-python-app cache [OPTIONS] COMMAND [ARGS]...

Commands:
  dir         Print the cache root directory
  list        List cached templates and extensions
  clean       Remove one or all entries
  verify      Run `git fsck` on one or all entries
  outdated    List cached entries that are behind their remote tip
  update      Refresh one or all cached entries from their remote
  doctor      Diagnose cache health (git, network, permissions)

Inspect and manage the on-disk cache:

# Where is my cache?
uvx create-awesome-python-app cache dir
# /home/<you>/.cache/cpa

# What's in it?
uvx create-awesome-python-app cache list

# Verify integrity
uvx create-awesome-python-app cache verify

# Clear everything
uvx create-awesome-python-app cache clean

# Check for outdated entries
uvx create-awesome-python-app cache outdated

# Refresh a specific entry (or all)
uvx create-awesome-python-app cache update

# Diagnose cache health
uvx create-awesome-python-app cache doctor

Cache & Updates

CPA caches both the template catalog (templates.json from raw.githubusercontent.com) and the template git repos themselves. The cache lives at ~/.cache/cpa by default; override with --cache-dir <path> or CPA_CACHE_DIR.

Refresh modes (set with --refresh <mode> or CPA_REFRESH=<mode>)

• stale (default): pull only when the cache is older than CPA_REFRESH_AFTER_HOURS (default 24). No network on a warm cache.
• always: pull on every run.
• manual: never pull unless --refresh is passed.

Pinning templates

Pin a template to a specific commit SHA, tag, or branch:

uvx create-awesome-python-app my-app \
  --template fastapi-starter \
  --pin abc123def456abc123def456abc123def456abc1 \
  --no-interactive

The --pin flag is equivalent to appending ?ref=<ref> to the template URL. Combine with CPA_STRICT_REPRO=1 to enforce full 40-character SHAs.

CI and offline usage

# Fully offline CI: use the local cache only, no network.
uvx create-awesome-python-app my-app \
  --template fastapi-starter \
  --offline \
  --no-interactive

# Pin the cache to a project-local directory (useful in monorepos and CI).
CPA_CACHE_DIR="$PWD/.cpa-cache" uvx create-awesome-python-app my-app \
  --template fastapi-starter \
  --no-interactive

Programmatic Usage

Need to integrate CPA into your own tooling? The core is importable:

import asyncio
from create_python_app_core import create_python_app

asyncio.run(
    create_python_app(
        "my-app",
        {
            "template": (
                "https://github.com/Create-Python-App/cpa-templates"
                "?subdir=templates/fastapi-starter"
            ),
            "addons": [],
            "install": False,
        },
    )
)

The programmatic API is experimental and subject to change. Prefer the CLI for stable usage.

See also: create-python-app-core README.

Security

CPA downloads templates from remote sources. Prefer catalog slugs or hash-pinned refs (--pin / ?ref=), audit custom URLs before use, and report vulnerabilities via GitHub Security Advisories on Create-Python-App/create-python-app.

FAQ

Roadmap

• More framework templates and vertical starters.
• Additional testing and observability packs.
• Diff-based upgrade paths for pinned templates.
• Richer template analytics and usage insights.

Track progress in Issues and Discussions.

Contributing

Templates, addons, bug fixes, docs, recipes, and ideas are all welcome.

• Main repo: github.com/Create-Python-App/create-python-app
• Template and extension data: github.com/Create-Python-App/cpa-templates
• Contributing guide: CONTRIBUTING.md
• Troubleshooting: docs/TROUBLESHOOTING.md

License

MIT © Create Python App Contributors