Skip to content
Get packs

Guide · Open source

How to use cookiecutter-data-science: install and start a project

Updated · written with AI from the project's own documentation and checked against our catalogue data

Cookiecutter Data Science (CCDS) is a command-line tool that creates a starter folder structure for a data science project. It separates raw and processed data, notebooks, models, reports and source code into predictable places. This guide shows you how to install it, generate a project with the ccds command, and understand what each folder is for.

CCDSdrivendataorg/cookiecutter-data-science · ★ 10.1k · MIT

Quick start

  1. 1Install with pipx. Run pipx install cookiecutter-data-science. Python 3.10 or newer is required.
  2. 2Run ccds. Run the ccds command in the folder where you want the project created, and answer the prompts.
  3. 3Review the layout. Check the generated data, notebooks, models and reports folders against your workflow.
  4. 4Put raw data in data/raw. Keep the original data dump in data/raw unchanged, and write transformed data to data/interim or data/processed.
  5. 5Name notebooks by convention. Name notebooks with a number, your initials and a short description, such as 1.0-jqp-initial-data-exploration.
  6. 6Pin a template version if needed. Use ccds -c with a branch, tag or commit hash if you need a template version other than the one matching your installed package.

Install cookiecutter-data-science

CCDS v2 requires Python 3.10 or newer. The README recommends installing it with pipx, because it is a cross-project utility application. You can also install it with pip.

  • Recommended: use pipx from PyPI.
  • Alternative: use pip from PyPI.
  • A conda-forge package is mentioned in the README as coming soon, so it is not available yet.
pipx install cookiecutter-data-science # or pip install cookiecutter-data-science

Start a new project with ccds

To create a project, run the ccds command. Version 2 uses ccds instead of cookiecutter, so you do not call cookiecutter directly for the current template. The README notes that the output depends on the settings you choose during the prompts.

ccds

Understand the project folder structure

The generated project separates work into predictable places. Raw data is kept apart from processed data, notebooks and models have their own folders, and source code lives in a Python package named after your project module. The README's example layout includes these main parts:

  • data/ with external, interim, processed and raw subfolders. Raw data is described as the original, immutable data dump.
  • models/ for trained and serialized models, predictions or summaries.
  • notebooks/ for Jupyter notebooks, named with a number, the creator's initials and a short description, e.g. 1.0-jqp-initial-data-exploration.
  • reports/ for generated analysis, with a figures/ subfolder for graphics.
  • references/ for data dictionaries, manuals and other explanatory material.
  • docs/ as a default mkdocs project.
  • A Makefile with convenience commands such as make data or make train.
  • pyproject.toml, requirements.txt and setup.cfg for configuration and dependencies.
  • A source code package containing config.py, dataset.py, features.py, plots.py and a modeling/ folder with train.py and predict.py.

Use a specific template version

By default, ccds uses the project template version that matches your installed ccds package. To use a different version, pass the -c or --checkout flag with a branch, tag or commit hash. The README's example uses the master branch.

ccds -c master

Use the old v1 template

If you need the v1 template, you need either the cookiecutter-data-science package or the cookiecutter package installed. Then run either program with the -c v1 option pointing at the repository URL.

  • v2 changed the tool and requires the new ccds command.
  • Use ccds or cookiecutter with -c v1 to get the older template.
ccds https://github.com/drivendataorg/cookiecutter-data-science -c v1 # or equivalently cookiecutter https://github.com/drivendataorg/cookiecutter-data-science -c v1

Contribute or run the tests

If you want to work on the project itself, the README asks you to install the development requirements and run the test suite. Contribution guidelines are in the project docs.

pip install -r dev-requirements.txt pytest tests

What people use it for

  • Starting a new modeling project with a consistent place for raw data, notebooks and models.
  • Giving a team shared conventions for where data, notebooks and models live.
  • Teaching students how a data science project can be organized.
  • Creating a data-science-specific project from a tool you already use with cookiecutter templates.

Frequently asked questions

Is cookiecutter-data-science free?

The project is released under the MIT licence, according to its listing. The generated project includes a LICENSE file only if you choose an open-source license during setup.

What are the requirements for cookiecutter-data-science?

CCDS v2 requires Python 3.10 or newer. The README recommends pipx for installation, and pip also works.

How do I install cookiecutter-data-science?

Run pipx install cookiecutter-data-science, which is the README's recommended method. Alternatively, run pip install cookiecutter-data-science.

What is the difference between ccds and cookiecutter?

In v2, you use the ccds command instead of cookiecutter. The README says v2 requires the new cookiecutter-data-science package, which extends the cookiecutter templating utility.

How do I use the old v1 template?

Install either the cookiecutter-data-science or cookiecutter package, then run ccds or cookiecutter with the repository URL and -c v1.

Can I use CCDS for a web application?

No. The README describes a data science project structure only, so it is not a web application or production service scaffold.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use cookiecutter-data-science if you are starting a data science or modeling project and want a consistent, shared folder layout for data, notebooks and models. Pick something else if you need a web app or production service scaffold, or if you prefer no standard folder structure, since the template is opinionated about folder names.

Install options & downloads