Python Project Foundry

Scaffold opinionated, production-ready Python package/library repositories with one command.

[!TIP] Read the Python Project Foundry documentation for the quickstart, configuration guides, generated-project reference, and update and publishing workflows.

Create a package/library repository

With uv installed, scaffold a repository directly from the published package:

uvx python-project-foundry /path/to/new/project

If uv is not installed, bootstrap it and scaffold the repository with one command on macOS or Linux:

curl -LsSf https://raw.githubusercontent.com/ryancswallace/python-project-foundry/main/ppf | sh -s -- /path/to/new/project

The launcher installs a compatible uv version when necessary, then runs Python Project Foundry in an isolated environment. No repository clone or separate setup command is required.

Both commands prompt for the template's answers and execute the generated repository's setup tasks. Run uvx python-project-foundry template --help to see options for unattended generation, overwriting files, previewing changes, and skipping setup tasks.

Update a generated repository

From a clean generated repository, preview and apply the template version bundled with the installed Foundry release:

uvx --refresh python-project-foundry update --pretend
uvx --refresh python-project-foundry update
make check

Copier preserves repository changes where possible and reports conflicts for manual review.

Contributor setup

For work on Python Project Foundry itself, make setup installs uv when needed and syncs the complete development environment:

make setup
make check