Comprehensive guide to using create-awesome-python-app
create-awesome-python-app is a powerful command-line tool designed to streamline the process of setting up modern Python applications. It provides a collection of carefully crafted templates and extensions that help developers quickly bootstrap projects with best practices and optimal configurations.
All generated projects now include a curated AGENTS.md file (powered by agents.md) that scopes how AI coding assistants (Cursor, GitHub Copilot Chat, PR bots) should interact with the repository. This keeps human documentation clean while giving AI precise operating guidelines.
Bootstrap projects in seconds with a single command
Choose from a variety of specialized project templates
Add only the features you need with optional extensions
Tailor templates to your specific requirements
Using create-awesome-python-app is straightforward. You can create a new project with a single command:
uvx create-awesome-python-app@latest my-appThis will launch an interactive CLI that guides you through selecting a template and optional extensions for your project.
Before using create-awesome-python-app, ensure you have the following installed:
The CLI supports several options to customize your project creation:
| Option | Description |
|---|---|
--version | Show the CLI version |
-i, --info | Print environment debug info |
-v, --verbose | Print additional logs |
-t, --template <template> | Specify a template slug (e.g. fastapi-starter) |
--addons [extensions...] | Apply one or more extensions during scaffolding |
--extend <extension> | Apply a single extension (repeatable) |
--set <key=value> | Set template or extension variables non-interactively |
--no-install | Scaffold the project without running uv sync |
-f, --force | Overwrite the target directory if it already exists |
--interactive / --no-interactive | Enable or disable the guided template/extension prompts |
--list-templates | List all available templates |
--list-addons | List all available extensions |
--offline | Use cached catalog and templates only |
--no-cache / --cache-dir | Control the local template cache location and behavior |
--pin / --refresh / --strict-version | Pin, refresh, or strictly resolve catalog versions |
--keep-on-failure | Keep partially generated files when scaffolding fails |
--install-completion / --show-completion | Install or print shell completion scripts |
cache | Manage the local template cache (subcommand) |
-h, --help | Display help for command |
Create a project with interactive mode:
uvx create-awesome-python-app my-app --interactiveCreate a project with a specific template:
uvx create-awesome-python-app@latest my-app --template fastapi-starterCreate a project with a template and extensions:
uvx create-awesome-python-app@latest my-app --template fastapi-starter --addons fastapi-docker github-setupList all available templates:
uvx create-awesome-python-app --list-templatesList all available extensions:
uvx create-awesome-python-app --list-addonscreate-awesome-python-app offers a variety of templates for different types of applications:
5 production-ready templates
FastAPI, Django API, CLI, Celery worker, and uv workspace monorepo starters.