What is Cookiecutter?

Cookiecutter is a templating library for creating boilerplate for projects in any programming language. In this article, we dig deeper into Cookiecutter’s capabilities, use cases, and tradeoffs.

Share this article

What is Cookiecutter?

Cookiecutter is a Python package, easily installable with pip or other package managers, that enables you to create and use templates for microservices and software projects. It is a command-line tool that requires no knowledge of Python to use. Cookiecutter is widely used among software engineers, researchers, data scientists, and other technical roles.

At its simplest, creating a template requires updating a cookiecutter.json file, while using a template requires running the cookiecutter command with the appropriate directory to create a new project.

Here’s an example template for a Python package that the Cookiecutter team maintains. To use the template, install Cookiecutter first and then run the following command in your terminal:

cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage.git

Go through the series of prompts and voila! In just a few moments you have the skeleton of a completely functional Python package. Swap out the template for something else and you could just as easily spin up a mobile app, a data science notebook, or a project on your favorite cloud service. There’s an entire community with thousands of templates to choose from.

Creating custom templates to fit your and your organization’s needs is also incredibly powerful. We’ll cover how to do that down below.

Who is Cookiecutter for?

Cookiecutter is for individuals, teams, and companies wanting to standardize their project development process and accelerate new project creation.

Example use cases include:

Learning a new framework: Cookiecutter lowers the barrier to entry for developers unfamiliar with a particular framework. You can find an expert’s template for a framework you’re learning and quickly get started with a configuration that is known to work.
Onboarding: Standardization makes collaboration much easier. New team members can immediately follow best practices without the risks of copying, pasting, and trying to edit just the right variables.
Enforcing standards in an organization: Consistent foldering, file naming conventions, and other patterns enable large teams to maintain an organized codebase.

Features of Cookiecutter

Templates

The heart of a template is the cookiecutter.json file, which might look something like this:

{

"full_name": "Alice Cookie",

"email": "foobar@example.com",

"project_name": "Django Boilerplate",

"version": "0.1.0"

}

‍
These key-value pairs determine the prompts a developer needs to answer when using a template. The command-line interface iterates over the keys, prompting a developer to set the various parameters. If a developer does not specify something, the values from the file are defaults that Cookiecutter uses.

Cookiecutter uses these inputs to modify the template. A template needs to have files and directories that are worth copying and reusing, such as the skeleton code for a particular framework. To connect this boilerplate to the inputs, Cookiecutter uses the Jinja2 templating language. With Jinja2, Cookiecutter identifies all instances of the text {{cookiecutter.variable_name}} and replaces that boilerplate with the actual value of the variable. This works both within files as well as for file and directory names.

Loops and Conditional Logic

Jinja2 is very powerful and can do much more than just text substitution. It comes with control structures including for loops and if statements. It even has macros, which are analogous to functions in programming languages. Since all of Cookiecutter’s templating uses Jinja2, it can leverage the same control flow features. This opens enormous possibilities. For example, you could prompt a developer to specify which device types they are building an app for and have unique behaviors depending on the response.

Hooks

Pre/post-generate hooks let you run Python or shell scripts before and/or after generating a project. Inputs from the template prompts are fair game within hooks and work similarly to elsewhere in the project with Jinja2 syntax. This means you can run a script to validate a developer’s responses to the prompts. Other applications of hooks include cleaning up unwanted files or otherwise using logic that would be complicated with just Jinja2.

What are Cookiecutter’s limitations?

By design, templates are prescriptive about a project’s setup, presenting all kinds of advantages as discussed above. On the other hand, a template might be opinionated in a way that does not align with either an individual developer’s or an organization’s preferences, in which case it may be worth choosing another template or revising an existing one. Forcing a template in a situation that doesn’t make sense is less than ideal.