Cookiecutter template for a Python package with production-ready CI and automated PyPI publishing. Push a tag, your package ships, no token management needed.
uvx cookiecutter-pypackage| Tool | ||
|---|---|---|
| Package manager | uv | Fast, handles venvs automatically |
| Task runner | just | just qa formats, lints, type-checks, and tests |
| Linting | ruff | Format + lint in one tool |
| Type checking | ty | All rules enabled, watch mode with just type-check-watch |
| Testing | pytest | Python 3.12, 3.13, 3.14 |
| CLI framework | Typer | Entry point + __main__.py included |
| Docs | Zensical + mkdocstrings | Auto-deployed to GitHub Pages, API docs from docstrings |
CI/CD (GitHub Actions, security-hardened)
| Workflow | Trigger | What happens |
|---|---|---|
| CI | Push, 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 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). Then push to GitHub and follow the tutorial to enable Pages and set up PyPI publishing.
Without uvx
uv venv
source .venv/bin/activate
uv pip install cookiecutter
cookiecutter gh:audreyfeldroy/cookiecutter-pypackageaudreyfeldroy.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.
Discord | MIT license