Cookiecutter Basics

What is Cookiecutter

Cookiecutter is a Python CLI tool that generates projects from templates. It was created by Audrey Feldroy (then Audrey Roy Greenfeld) in 2013 and has become the de facto standard for project scaffolding.

Key features:

• Templates defined as directories with Jinja2 in file names and content.
• Configuration variables in cookiecutter.json.
• Pre/post generation hooks in Python.
• Works with any language, not just Python.
• Supports templates from Git, URLs, or local paths.

---

Installation

# With pip
pip install cookiecutter

# With pipx (recommended — isolated install)
pipx install cookiecutter

# With conda
conda install -c conda-forge cookiecutter

Requirements: Python 3.7+

Verify installation:

cookiecutter --version

---

Basic Usage

From a Git URL

# HTTPS
cookiecutter https://github.com/user/cookiecutter-my-template.git

# SSH
cookiecutter git@github.com:user/cookiecutter-my-template.git

From a local path

cookiecutter ./my-template
cookiecutter /absolute/path/to/template

Non-interactive mode

cookiecutter --no-input ./my-template project_name=my-project license=MIT

Specify branch or tag

cookiecutter https://github.com/user/template.git --checkout v1.0
cookiecutter https://github.com/user/template.git --checkout develop

Re-use default values

# Use defaults from cookiecutter.json without prompting
cookiecutter --no-input ./my-template
# Override only some variables
cookiecutter --no-input ./my-template project_name=foo author=bar

---

Interactive Flow

When running cookiecutter on a template, a prompt is presented for each variable in cookiecutter.json:

project_name [My Project]: my-project
project_slug [my_project]:
author_name [Your Name]: Jane Doe
license [MIT]:

• The value in brackets [...] is the default (from cookiecutter.json).
• Pressing Enter accepts the default.
• The entered value is used in Jinja2 as {{ cookiecutter.project_name }}.

---

Minimal Template Structure

my-template/
├── cookiecutter.json
└── {{ cookiecutter.project_name }}/
    ├── README.md
    └── ...

cookiecutter.json:

{
  "project_name": "My Project",
  "project_slug": "my_project"
}

{{ cookiecutter.project_name }}/README.md:

# {{ cookiecutter.project_name }}

Generated with cookiecutter.

When running cookiecutter ./my-template with project_name=My App:

My App/
├── README.md   # "# My App\n\nGenerated with cookiecutter."

---

CLI Options

Option	Description
--no-input	Do not prompt, use defaults or passed values
--checkout BRANCH	Branch, tag, or commit to use
--directory DIR	Subdirectory within the repo containing the template
--output-dir DIR	Directory where the project is generated (default: .)
--overwrite-if-exists	Overwrite if the directory already exists
--skip-if-file-exists	Do not generate if it already exists (useful in CI)
--config-file FILE	User config file
--default-config-file FILE	Default config file
--keep-project-on-failure	Do not delete the project if a hook fails

---

User Configuration

Cookiecutter can read defaults from ~/.cookiecutterrc or ~/.config/cookiecutter/config.yml:

# ~/.cookiecutterrc
default_context:
  author_name: "Jane Doe"
  license: "MIT"
  github_username: "janedoe"

These values are used as global defaults for all templates.

---

Next Steps

• Template Structure — detailed anatomy.
• Hooks Guide — pre/post generation scripts.
• Creating Your Own Template — step-by-step tutorial.