Cookiecutter template for a Python package with production-ready CI and automated PyPI publishing.
- GitHub | PyPI | Documentation
- Created by Audrey M. Roy Greenfeld | GitHub @audreyfeldroy | PyPI @audreyr
- MIT License
| Tool | ||
|---|---|---|
| Package manager | uv | Fast, handles venvs automatically |
| Task runner | just | just fix applies safe fixes, just check verifies, and just fix-and-check does both |
| Linting | ruff | Format + lint in one tool |
| Type checking | ty | All rules enabled, watch mode with just type-check-watch |
| Testing | pytest | just check tests Python 3.14; just testall and CI cover 3.12, 3.13, and 3.14 |
| CLI framework | Typer | Entry point + __main__.py included |
| Docs | Zensical + mkdocstrings | GitHub Pages deployment, API docs from docstrings |
CI/CD (GitHub Actions, security-hardened)
| Workflow | Trigger | What happens |
|---|---|---|
| CI | Push to main, PRs | Lint, type check, test across 3 Python versions |
| Publish | v* tag |
Build, Sigstore attestation, PyPI via Trusted Publishers (no tokens) |
| Docs | Push to main | Build and deploy to GitHub Pages |
| Dependabot | Weekly | PRs to update Python dependencies and SHA-pinned actions |
All actions pinned by SHA, minimal permissions, no persisted credentials.
Install uv, then:
uvx cookiecutter-pypackageYou'll be prompted for your package name, GitHub username, and a few other values (full list). Follow the tutorial to generate, verify, and release your package.
Without uvx
uv venv
source .venv/bin/activate
uv pip install cookiecutter
cookiecutter --keep-project-on-failure gh:audreyfeldroy/cookiecutter-pypackagePass key=value arguments to prefill prompts, or add --no-input for
automation:
uvx cookiecutter-pypackage full_name="Your Name"See Template prompts and command-line options for all variables, defaults, and automation options.
audreyfeldroy.github.io/cookiecutter-pypackage
- Tutorial - from generation to first PyPI release
- Project Structure - what's in the generated project
- GitHub Actions - CI, publish, docs deployment, security hardening
- Prompts - what each prompt means
- Troubleshooting
This template is opinionated. If it doesn't fit:
- Browse the fork network for variants
- Create your own template from scratch
Pull requests welcome if they're small, atomic, and improve the template.
I maintain Cookiecutter PyPackage as part of how I build software. I’m also building Stead, a home for your creative work with less website maintenance to think about.
I used Stead to create a home for our Ambria series. It makes me feel better about relaunching the books, without the mental overhead of maintaining another website.
If Cookiecutter PyPackage has helped you, I’d love it if you helped sustain my open-source work by exploring Stead or sharing it with a creator who wants a home for their work.
Discord | MIT license