Advanced Usage
Advanced techniques and configurations for create-awesome-python-app
Working with uv in Generated Projects
Every CPA template is uv-first: dependencies live in pyproject.toml, the lockfile is uv.lock, and day-to-day commands go through uv run.
# Create a project (uv sync runs automatically unless --no-install) uvx create-awesome-python-app@latest my-app --template fastapi-starter # Install or refresh dependencies later cd my-app uv sync
Skip automatic install
--no-install when scaffolding if you want to review pyproject.toml before running uv sync yourself.CI/CD Integration
Most templates offer extensions that include files for different CI/CD tools. These extensions provide ready-to-use configurations for popular CI/CD platforms:
GitHub Actions
The GitHub Setup extension adds GitHub Actions workflows for CI/CD, along with issue templates and other GitHub-specific configurations.
uvx create-awesome-python-app@latest my-app --template fastapi-starter --addons github-setup
Docker
The python-docker extension adds a Dockerfile and Compose files for local and production container runs.
uvx create-awesome-python-app@latest my-app --template fastapi-starter --addons python-docker
Deployment Workflow
Here's a typical deployment workflow for a create-awesome-python-app project:
Deployment Workflow
Monorepo Setup
create-awesome-python-app offers the uv-workspace-starter template for Python monorepos with a single lockfile and shared tooling:
# Create a new uv workspace monorepo uvx create-awesome-python-app@latest my-monorepo --template uv-workspace-starter # Navigate to the project cd my-monorepo # Sync all workspace members uv sync # Run a member app (example) uv run --package apps-api uvicorn app.main:app --reload # Run tests across the workspace uv run pytest
The uv workspace starter includes:
- uv workspace configuration with shared
pyproject.tomltooling - Separate
packages/libraries andapps/deployables - Shared Ruff, Pyright, and pytest configuration
- Example members demonstrating cross-package imports
Troubleshooting Common Issues
Installation Failures
If you encounter issues during installation:
Problem: Dependencies fail to install
Solution: Try using the --no-install flag and then install dependencies manually
uvx create-awesome-python-app my-app --no-installcd my-app && uv syncTemplate or Extension Not Found
If a template or extension is not found:
Problem: Specified template or extension doesn't exist
Solution: List available templates and extensions to check the correct names
uvx create-awesome-python-app --list-templatesuvx create-awesome-python-app --list-addonsCompatibility Issues
If you encounter compatibility issues between templates and extensions:
Problem: Extension is not compatible with the selected template
Solution: Check the extension's compatibility in the documentation or use the interactive mode
uvx create-awesome-python-app my-app --interactiveDebugging Tips
- Use the
--verboseflag to see detailed logs during project creation - Check the
--infoflag to print environment debug information - If all else fails, try creating a project with minimal options and then add features manually
Available Templates and Extensions
create-awesome-python-app offers a variety of templates and extensions. Here's how to list them:
# List all available templates uvx create-awesome-python-app --list-templates # List all available extensions uvx create-awesome-python-app --list-addons
You can also view the templates and extensions on the project's website or GitHub repository.
Interactive Mode
The interactive mode provides a guided experience for creating projects:
uvx create-awesome-python-app my-app --interactive
In interactive mode, you'll be prompted to:
- Select a template from the available options
- Choose extensions compatible with the selected template
- Configure template-specific options (if available)
- Confirm your choices before project creation
This mode is especially useful for beginners or when you're not sure which template or extensions to use.