Cookiecutter PyPackage

• GitHub | PyPI | Documentation
• Created by Audrey M. Roy Greenfeld | GitHub @audreyfeldroy | PyPI @audreyr
• MIT License

Cookiecutter template for a Python package with production-ready CI and automated PyPI publishing.

uvx cookiecutter-pypackage

What you get

Tooling

	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, 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.

Quickstart

Install uv, then:

uvx cookiecutter-pypackage

You'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.

After the template prompts, you can optionally set up GitHub. The default is no: pressing Enter creates only the project files. If you opt in, the generator shows its complete plan before it creates a private or public repository, makes the first Git commit, creates the pypi environment, and pushes main. Public repositories enable Pages by default. For private repositories, Pages defaults to off because the site can still be public and the feature may require a paid GitHub plan. The docs deployment workflow follows that choice, so declining Pages does not create a failed workflow on the first push.

Without uvx

uv venv
source .venv/bin/activate
uv pip install cookiecutter
cookiecutter --keep-project-on-failure gh:audreyfeldroy/cookiecutter-pypackage

Override template variables

Pass key=value arguments to prefill the interactive prompts. You can still review or change each value:

uvx cookiecutter-pypackage \
    full_name="Your Name" \
    github_username=yourhandle

For non-interactive automation, add --no-input before the overrides. Variables you don't pass use the defaults in cookiecutter.json:

uvx cookiecutter-pypackage --no-input \
    full_name="Your Name" \
    email="you@example.com"

Non-interactive generation skips GitHub setup unless you explicitly request a private or public repository:

uvx cookiecutter-pypackage --no-input --github private \
    full_name="Your Name" \
    email="you@example.com" \
    github_username=yourhandle \
    author_website="" \
    project_name="My Package" \
    package_name=my-package

--github public also enables Pages and docs deployment. --github private leaves both disabled; run interactively if you want to acknowledge the visibility warning and enable them. If requested GitHub setup fails, the command exits nonzero and keeps the generated directory for recovery.

Use --github skip to suppress the GitHub question during an interactive generation.

List the available variables and their configured defaults without generating a project:

uvx cookiecutter-pypackage --list-variables

Quote values that contain spaces so the shell passes each assignment as one argument:

full_name="First Last"  # correct
full_name=First Last    # incorrect

See the template prompts for descriptions of all available variables.

Documentation

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

Alternatives

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