🍪 Python Cookiecutter

A framework-agnostic cookiecutter template for starting a modern Python project.

What this template includes

• Python 3.12+ default
• src/ package layout
• Poetry for dependency management
• In-project virtual environments via poetry.toml (.venv/)
• Ruff for linting and formatting
• MyPy for strict static type checking
• Pytest for testing
• Dependabot config for dependency update automation
• A practical Makefile for common workflows
• Shared AI assistant guidance via AGENTS.md

Template dependency baseline

[tool.poetry.dependencies]
python = "^{{cookiecutter.python_version}}"

[tool.poetry.group.dev.dependencies]
pytest = "^8.3"
mypy = "^1.11"
ruff = "^0.6"

Install cookiecutter

pip install cookiecutter

Create a project

cookiecutter gh:ambersariya/cookiecutter-python

Example prompts:

project_name [some project name]: example_proj
project_short_description [A project to]: Captures screenshots of webpages
project_slug [example_proj]:
package_slug [example_proj]:
python_version [3.12]:
version [0.1.0]:
full_name [Firstname Lastname]: Firstname Lastname
email [username@example.org]: firstname@example.org
license []:
homepage_url [https://example.com/example_proj]:
repository_url [https://github.com/your-org/example_proj]:

Validate generated project

cd example_proj
poetry install
make check

Initial git setup

git init
git add .
git commit -m "feat: initial scaffold"
git push -u origin main