How to Spin Up a Project Structure with Cookiecutter

you’re anything like me, “procrastination” might as well be your middle name. There’s always that nagging hesitation before starting a new project. Just thinking about setting up the project structure, creating documentation, or writing a decent README is enough to trigger yawns. It feels like staring at a blank page for a dreaded school essay. But remember how much easier it gets once some helpful LLM (like ChatGPT) provides a starting template? The same magic can apply to your coding projects. That’s where Cookiecutter steps in.

What Is Cookiecutter? 

Cookiecutter is an open-source tool that helps you create project templates. It is language-agnostic and works with virtually any programming language (or even outside coding, should you need a standardized folder and file structure). With Cookiecutter, you can set up all the boilerplate files (like READMEs, Dockerfiles, project directories, or anything else), then quickly generate new projects based on that structure.

The Cookiecutter workflow consists of three main steps:

1. You define your project template.
2. The user enters values for the variables you specify.
3. Cookiecutter generates a new project, automatically filling in files, folders, and variable values based on the user’s input.

The following image illustrates this process:

1. Basic Computer Setup

You need minimal programming skills to install and use Cookiecutter. If you can open a command line window, you’re good to go.

• On Windows, type “cmd” in the search bar and open the “Command Prompt.” 

• If you haven’t already, install pipx with:

pip install pipx

Test your installation by running: 

pipx --version

If you get a “command not found” error, add pipx to your PATH. First, find where pipx was installed: python -m site –user-base.

This might return something like /home/username/.local. Look for the folder containing pipx.exe (on Windows) or pipx (on macOS or Linux). If you have no admin rights, the directory might be C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts.

I had to add pipx to my path and if you don’t have admin rights, you will need to do it each time you start a new terminal window. It is therefore recommended to add the location permanently to your Environment Variables settings. However, if this setting is behind admin privileges, you still can add

set PATH=C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts;%PATH%

Or

set PATH=/home/username/.local/bin;%PATH%

Hopefully, you get a meaningful response for pipx --version now.

2. Installing and Setting Up Cookiecutter

Cookiecutter is distributed as a Python package, so you can install it with pipx:

  pipx install cookiecutter 

Or simply run it on the fly with: 

  pipx run cookiecutter ...

Let’s walk through creating a project template. In this example, we’ll set up a template for Streamlit apps (cookiecutter_streamlit_ml). 

3. Creating the Template Structure

Inside your cookiecutter_streamlit_ml folder, you need these two key components:

• cookiecutter.json – a JSON file that defines the variables you want users to fill in (project name, author, Python version, etc.). 

• {{ cookiecutter.directory_name }} – A placeholder folder name defined using curly braces. This directory will contain your project’s structure and files. When the user creates a new project from your template, Cookiecutter will replace this placeholder with the name they provided. Watch out to keep the curly braces! 

Your cookiecutter.json might look something like this:

First, you define variables in cookiecutter.json that are used throughout the generated project. At a minimum, you’ll want a variable for the project name.

For example, I often reference my GitHub repository in documentation. Rather than entering it repeatedly, I set a variable once and let Cookiecutter populate every instance automatically. Similarly, I don’t want to write out my name in each readme or documentation file, so I set it at the start.

To avoid issues with Docker and make sure the correct Python version is specified, I prompt for the Python version at project creation, ensuring it is used in the generated Dockerfile.

You can define default values for each field in cookiecutter.json. Cookiecutter will automatically replace every instance of {{ cookiecutter.variable }} in your template files with the user’s input. You can also use transformations like lower() or replace(‘ ‘, ‘_’) to avoid issues with spaces in directory names.

In my template, I prefer providing detailed instructions to users rather than setting default values. This helps guide those who might skip reading the README and jump straight into project creation.

4. Building Out Your Template

Now begins the fun part, namely defining your template. You are doing it once and for all, so it is worthwhile to spend some time on it, which will drastically reduce your project setup time in the long run.

First, create the folder structure for your project. This includes creating all folders that you expect to use in your project. Don’t worry, whatever is missing or turns out to be superfluous can be edited in the actual project. For now, you are merely creating the blueprint; the whistles and bells will be project-specific.

Once you have your folders ready, you can populate them with files. These can be either empty or even have some content that you might otherwise constantly copy-paste from other documents. In these files, refer to your cookiecutter variables wherever something needs to be set dynamically (e.g., the project name or the GitHub repo). Cookiecutter will automatically replace those placeholders with user inputs, which will be asked for during project setup. This spares you a lot of tedious copy-paste work, particularly in your documentation files.

Lastly, deposit the whole cookiecutter_py_streamlit folder in your GitHub account, zip it, or leave it as it is. Either way, you can now …

5. Use your template

Once your template is ready, creating a new project becomes a snap:

1. Open your terminal and navigate to where you’d like to create the project. 

2. Run one of the following commands:

   • From GitHub: 

     pipx run cookiecutter gh:ElenJ/cookiecutter_streamlit_ml  (replace with your repo)

   • From a local folder: 

     pipx run cookiecutter /path/to/template_folder 

   • From a zip: 

     pipx run cookiecutter /path/to/template.zip 

3. Cookiecutter will ask you the questions defined in cookiecutter.json. Provide answers—or just press enter if you’ve set default values. 

4. Voilà 🎉 your new project folder is generated, complete with folders, files, and references customized to your inputs.

You can synchronize your new project with GitHub by either pushing it directly from your IDE’s built-in Git functionality or by creating a new repo on GitHub (ensuring it’s empty and doesn’t include a Readme) and then moving your generated project folder there.

And that’s it! You’ve turned what used to be a day-long chore into a swift process and have instantly generated lots of files waiting to be filled in with your ideas. Looking at the new project, you definitely should have a feeling of a productive day. If you’re still looking for guidance on best practices, check out the official Cookiecutter templates here.

And as always: Happy coding!