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. When WriterStead needs new Air packages, I improve the shared foundation here first so other Python developers can benefit too.
If Cookiecutter PyPackage has helped you, I’d love it if you helped me sustain my efforts here by showing WriterStead some love: join the early-access list, or introduce it to a writer friend who wants a website or blog.
Discord | MIT license