cookiecutter

Cookiecutter turns any directory with a cookiecutter.json file and Jinja2 placeholders into a reusable project template. Point it at a local folder or a Git-hosted template (GitHub shorthand like gh:user/repo works out of the box) and it clones the template, prompts for the variables the template defines, and renders every file and directory name through Jinja2 to produce a finished project in seconds.

Beyond simple variable substitution, it supports pre- and post-generation hooks (Python or shell scripts) for tasks like initializing git, installing dependencies, or removing conditional files based on user answers; a replay mode that re-runs a template with previously saved answers; and nested/multi-template repos where users pick from several templates in one repository. Custom Jinja2 extensions ship built in for JSON serialization, slugification, UUIDs, random strings, and date arithmetic.

Because it has no opinion about the target language or framework, cookiecutter templates exist for Python packaging, Django and FastAPI apps, Rust crates, Terraform modules, documentation sites, and general boilerplate of every kind — the tool only cares about rendering text, not what that text is.

What You Get

• A CLI entry point (cookiecutter) that scaffolds projects from any local directory or Git-hosted template, including a gh:user/repo shorthand for GitHub-hosted templates
• Jinja2-based rendering of file contents, filenames, and directory names driven entirely by a template’s cookiecutter.json variable manifest
• Pre-prompt, pre-generate, and post-generate hook support (Python or shell scripts) for running setup steps like git init, dependency installs, or conditional file removal
• A replay system that stores each run’s answers as JSON so a template can be regenerated non-interactively with the same inputs
• Support for nested/multi-template repositories, letting one repo offer several template choices to the user
• Built-in Jinja2 extensions for JSON serialization, slugification, UUID generation, random strings, and relative date/time formatting

Common Use Cases

• Bootstrapping a new Python package from a maintained template like cookiecutter-pypackage, complete with packaging config, CI, and test scaffolding
• Standardizing internal project layout across a team or organization by maintaining a private template repo with agreed-upon structure and tooling
• Generating framework-specific starters (Django apps, FastAPI services, data-science project layouts) from community or in-house templates
• Scripting project creation as part of a larger workflow by calling cookiecutter() programmatically from Python instead of the CLI
• Non-interactive/CI project generation using no_input=True with extra_context overrides or a saved replay file

Under The Hood

Architecture Execution starts in cookiecutter/main.py’s cookiecutter() function, which orchestrates the whole pipeline: it loads user config (config.py), resolves the template location — local path or cloned Git repo — via determine_repo_dir() in repository.py/vcs.py, optionally runs a pre-prompt hook (hooks.py), builds the variable context from cookiecutter.json (generate_context() in generate.py), prompts interactively for any unset values (prompt.py), then hands off to generate_files() which walks the template tree and renders each path and file through a Jinja2 Environment built by environment.py/extensions.py. The design is a clear linear pipeline (config → repo resolution → context → prompt → render) with each stage isolated in its own module, and hooks/replay act as extension points rather than special-cased branches — a change to the core Jinja environment or context shape ripples through generate.py and prompt.py but the CLI (cli.py) and the public cookiecutter() function stay stable as the integration surface for both interactive and programmatic use.

Tech Stack Pure Python 3.10+ with a small, deliberate dependency set: Jinja2 for templating, Click for the CLI, rich for prompt/console rendering, PyYAML for config file parsing, python-slugify for the slugify filter, arrow for the {% now %} date extension, binaryornot to detect files that should be copied rather than rendered, and requests for fetching remote resources. The project builds and manages its dev environment with uv and a justfile, lints and formats with ruff (a broad rule set including bandit-derived security checks), type-checks with mypy --strict, and documents itself via Sphinx with sphinx_click for auto-generated CLI reference docs.

Code Quality 50 test modules exercise nearly every code path — hooks, replay, nested templates, copy-without-render overrides, config loading, VCS cloning, and CLI argument handling — using pytest with pytest-mock and freezegun for deterministic time-dependent tests. mypy runs in strict mode across the package (with narrow, explicit overrides for a couple of modules), custom exception types in exceptions.py give callers precise failure modes instead of bare exceptions, and CI (.github/workflows/tests.yml) runs the suite on every push. Naming and structure are consistent and the ruff configuration enables an unusually wide set of lint categories (bugbear, bandit, simplify, pyupgrade, and more) for a project of this size.

What Makes It Unique Cookiecutter’s defining choice is language-and-framework agnosticism: a template is nothing more than a directory of Jinja2-renderable paths plus a JSON variable manifest, so the same engine scaffolds Python packages, Terraform modules, or arbitrary text-based boilerplate without any built-in notion of what it’s generating. The replay mechanism and pre/post-generate hook system let templates encode non-trivial setup logic (conditional deletion, external command execution) without requiring cookiecutter itself to grow framework-specific features — the tool stays a thin, general-purpose rendering engine while templates carry all domain-specific behavior, which is why the ecosystem around it (dozens of independently maintained community templates) is as large as it is.