A command-line utility that creates projects from cookiecutters (project templates), e.g. creating a Python package project from a Python package project template.
Simple command line usage:
# Create project from the cookiecutter-pypackage.git repo template
# You'll be prompted to enter values.
# Then it'll create your Python package in the current working directory,
# based on those values.
$ cookiecutter https://github.com/audreyfeldroy/cookiecutter-pypackage
# For the sake of brevity, repos on GitHub can just use the 'gh' prefix
$ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage
Use it at the command line with a local template:
# Create project in the current working directory, from the local
# cookiecutter-pypackage/ template
$ cookiecutter cookiecutter-pypackage/
Or use it from Python:
from cookiecutter.main import cookiecutter
# Create project from the cookiecutter-pypackage/ template
cookiecutter('cookiecutter-pypackage/')
# Create project from the cookiecutter-pypackage.git repo template
cookiecutter('https://github.com/audreyfeldroy/cookiecutter-pypackage.git')
Unless you suppress it with --no-input
, you are prompted for input:
cookiecutter.json
.cookiecutter.json
.Cross-platform support for ~/.cookiecutterrc
files:
default_context:
full_name: "Audrey Roy Greenfeld"
email: "audreyr@gmail.com"
github_username: "audreyfeldroy"
cookiecutters_dir: "~/.cookiecutters/"
Cookiecutters (cloned Cookiecutter project templates) are put into ~/.cookiecutters/
by default, or cookiecutters_dir if specified.
If you have already cloned a cookiecutter into ~/.cookiecutters/
, you can reference it by directory name:
# Clone cookiecutter-pypackage
$ cookiecutter gh:audreyfeldroy/cookiecutter-pypackage
# Now you can use the already cloned cookiecutter by name
$ cookiecutter cookiecutter-pypackage
You can use local cookiecutters, or remote cookiecutters directly from Git repos or Mercurial repos on Bitbucket.
Default context: specify key/value pairs that you want to be used as defaults whenever you generate a project.
Inject extra context with command-line arguments:
cookiecutter --no-input gh:msabramo/cookiecutter-supervisor program_name=foobar startsecs=10
Direct access to the Cookiecutter API allows for the injection of extra context.
Paths to local projects can be specified as absolute or relative. Projects are generated to your current directory or to the target directory if specified with -o
option.
Supports unlimited levels of directory nesting.
100% of templating is done with Jinja2.
Both, directory names and filenames can be templated. For example:
{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py
Simply define your template variables in a cookiecutter.json
file. You can also add human-readable questions and choices that will be prompted to the user for each variable using the __prompts__
key. Those human-readable questions supports rich
markup such as [bold yellow]this is bold and yellow[/]
For example:
{
"full_name": "Audrey Roy Greenfeld",
"email": "audreyr@gmail.com",
"project_name": "Complexity",
"repo_name": "complexity",
"project_short_description": "Refreshingly simple static site generator.",
"release_date": "2013-07-10",
"year": "2013",
"version": "0.1.1",
"linting": ["ruff", "flake8", "none"],
"__prompts__": {
"full_name": "Provide your [bold yellow]full name[/]",
"email": "Provide your [bold yellow]email[/]",
"linting": {
"__prompt__": "Which [bold yellow]linting tool[/] do you want to use?",
"ruff": "Ruff",
"flake8": "Flake8",
"none": "No linting tool"
}
}
}
Pre- and post-generate hooks: Python or shell scripts to run before or after generating a project.
Making great cookies takes a lot of cookiecutters and contributors. We're so pleased that there are many Cookiecutter project templates to choose from. We hope you find a cookiecutter that is just right for your needs.
The best place to start searching for specific and ready-to-use cookiecutter templates is Github search. Just type cookiecutter
and you will discover over 4000 related repositories.
We also recommend you check related GitHub topics. For general search use cookiecutter-template. For specific topics try to use cookiecutter-yourtopic
, like cookiecutter-python
or cookiecutter-datascience
. This is a new GitHub feature, so not all active repositories use it at the moment.
If you are a template developer please add related topics with cookiecutter
prefix to your repository. We believe it will make it more discoverable. You are almost not limited in topic amount, use it!
These Cookiecutters are maintained by the cookiecutter team:
The core committer team can be found in the authors' section. We are always welcome and invite you to participate.
Stuck? Try one of the following:
Development on Cookiecutter is community-driven:
Encouragement is unbelievably motivating. If you want more work done on Cookiecutter, show support:
Got criticism or complaints?
Waiting for a response to an issue/question?
This project is run by volunteers. Shortly we will be providing means for organizations and individuals to support the project.
Everyone interacting in the Cookiecutter project's codebases and documentation is expected to follow the PyPA Code of Conduct. This includes but is not limited to, issue trackers, chat rooms, mailing lists, and other virtual or in real-life communication.
This project was created and led by Audrey Roy Greenfeld.
She is supported by a team of maintainers.
Author: cookiecutter
Source: https://github.com/cookiecutter/cookiecutter
License: BSD-3-Clause license