Cookiecutter PyPackage¶
I built this template to give you everything a Python package needs, ready to go from the moment you generate it.
Answer a few prompts and you'll have a complete project: source code with a CLI, a test suite, a documentation site, and CI/CD that handles linting, type checking, testing, and publishing to PyPI.
Your project comes ready with¶
A real development workflow. uv manages your dependencies and virtual environments. just gives you explicit quality commands: just fix applies Ruff's automatic fixes, just check verifies formatting, linting, types, and tests on Python 3.14 without modifying source files, and just fix-and-check does both. Use just testall for the local Python 3.12, 3.13, and 3.14 test matrix; GitHub CI runs that matrix separately. A Typer CLI is wired up and working from the first uv sync.
A documentation site ready to deploy. Zensical
builds your docs with the Material theme, light and dark mode, and
mkdocstrings generates API reference pages
from your docstrings. Once you enable GitHub Pages and set
DOCS_DEPLOYMENT_ENABLED=true, a push to main publishes
the site. Preview locally with just docs-serve.
Automated PyPI publishing with no tokens to manage. Push a v* tag and GitHub Actions builds your package, signs it with Sigstore, and publishes via Trusted Publishers. OIDC handles authentication, so there are no API tokens to create, rotate, or leak.
Security-hardened CI you don't have to think about. Every GitHub Action is pinned by SHA. Permissions are minimal. Credentials aren't persisted after checkout. Dependabot opens PRs weekly to keep your actions current. See GitHub Actions for the full details.
Coverage that works the way coverage.py intends. Branch coverage, parallel mode, cross-version combining across Python 3.12, 3.13, and 3.14, and a fail_under floor you raise as your project grows. CI collects coverage from every Python version and posts a combined report to the GitHub Actions summary.
A clean project structure. src layout so you never accidentally import local code during testing. A py.typed marker and type hints on all starter code. __main__.py so your package works with python -m. A focused .gitignore instead of the 200-line GitHub default.
Justfile commands for everything. Use just fix-and-check for the daily workflow, or run just fix and just check separately. There are also focused commands including just test, just testall, just type-check-watch, just coverage, just docs-serve, and just release. Run just list to see them all. See Project Structure for the full table.
Your name on it. The generated README includes a bold "Created by" line linking to your GitHub profile, PyPI profile, and personal website. You built the package, you should get the credit.
Get started¶
The Tutorial walks you through everything: generating your package, running the tests, pushing to GitHub, deploying your docs, and publishing your first release to PyPI.
If something goes wrong, check Troubleshooting.