skip to navigation
skip to content

cookiecutter 0.7.2

A command-line utility that creates projects from project templates, e.g. creating a Python package project from a Python package project template.

Latest Version: 1.6.0


.. image::

.. image::

.. image::

.. image::

A command-line utility that creates projects from **cookiecutters** (project
templates), e.g. creating a Python package project from a Python package project template.

* Documentation:
* GitHub:
* Free software: BSD license
* PyPI:

.. image::


Did someone say features?

* Cross-platform: Windows, Mac, and Linux are officially supported.

* Works with Python 2.6, 2.7, 3.3, and PyPy. *(But you don't have to know/write Python
code to use Cookiecutter.)*

* Project templates can be in any programming language or markup format:
Python, JavaScript, Ruby, CoffeeScript, RST, Markdown, CSS, HTML, you name
it. You can use multiple languages in the same project template.

* Simple command line usage:

.. code-block:: bash

# 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

* Can also use it at the command line with a local template:

.. code-block:: bash

# Create project in the current working directory, from the local
# cookiecutter-pypackage/ template
$ cookiecutter cookiecutter-pypackage/

* Or use it from Python:

.. code-block:: python

from cookiecutter.main import cookiecutter

# Create project from the cookiecutter-pypackage/ template

# Create project from the cookiecutter-pypackage.git repo template

* Directory names and filenames can be templated. For example::


* Supports unlimited levels of directory nesting.

* 100% of templating is done with Jinja2. This includes file and directory names.

* Simply define your template variables in a `cookiecutter.json` file. For example:

.. code-block:: json

"full_name": "Audrey Roy",
"email": "",
"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"

* Unless you suppress it with `--no-input`, you are prompted for input:

- Prompts are the keys in `cookiecutter.json`.
- Default responses are the values in `cookiecutter.json`.
- Prompts are shown in order.

* Cross-platform support for `~/.cookiecutterrc` files:

.. code-block:: guess

full_name: "Audrey Roy"
email: ""
github_username: "audreyr"
cookiecutters_dir: "~/.cookiecutters/"

* Cookiecutters (cloned Cookiecutter project templates) are put into
`~/.cookiecutters/` by default, or cookiecutters_dir if specified.

* You can use local cookiecutters, or remote cookiecutters directly from Git
repos or from Mercurial repos on Bitbucket.

* Default context: specify key/value pairs that you want used as defaults
whenever you generate a project

* Pre- and post-generate hooks: Python or shell scripts to run before or after
generating a project.

* Paths to local projects can be specified as absolute or relative.

* Projects are always generated to your current directory.

Available Cookiecutters

Here is a list of **cookiecutters** (aka Cookiecutter project templates) for you to use or fork.

Make your own, then submit a pull request adding yours to this list!


* `cookiecutter-pypackage`_: `@audreyr`_'s ultimate Python package project
* `cookiecutter-flask`_ : A Flask template with Bootstrap 3, starter templates, and working user registration.
* `cookiecutter-simple-django`_: A cookiecutter template for creating reusable Django projects quickly.
* `cookiecutter-django`_: A bleeding edge Django project template with Bootstrap 3, customizable users app, starter templates, and working user registration.
* `cookiecutter-djangopackage`_: A template designed to create reusable third-party PyPI friendly Django apps. Documentation is written in tutorial format.
* `cookiecutter-django-cms`_: A template for Django CMS with simple Bootstrap 3 template. It has a quick start and deploy documentation.
* `cookiecutter-openstack`_: A template for an OpenStack project.
* `cookiecutter-docopt`_: A template for a Python command-line script that uses `docopt`_ for arguments parsing.
* `cookiecutter-django-crud`_: A template to create a Django app with boilerplate CRUD around a model including a factory and tests.
* `cookiecutter-quokka-module`_: A template to create a blueprint module for Quokka Flask CMS.
* `cookiecutter-django-lborgav`_: Another cookiecutter template for Django project with Booststrap 3 and FontAwesome 4.
* `cookiecutter-django-paas`_: Django template ready to use in SAAS platforms like Heroku, OpenShift, etc..
* `cookiecutter-kivy`_: A template for NUI applications built upon the kivy python-framework.
* `cookiecutter-pypackage-minimal`_: A mimimal Python package template.
* `cookiecutter-ansible-role`_: A template to create ansible roles. Forget about file creation and focus on actions.
* `cookiecutter-pylibrary`_: An intricate template designed to quickly get started with good testing and packaging (working configuration for Tox, Pytest, Travis-CI, Coveralls, AppVeyor, Sphinx docs, isort, bumpversion, packaging checks etc).
* `cookiecutter-pylibrary-minimal`_: Same as above but without Pytest and static configuration for Tox/Travis/AppVeyor (no generator).


* `bootstrap.c`_: A template for simple projects written in C with autotools.
* `cookiecutter-avr`_: A template for avr development.


* `BoilerplatePP`_: A simple cmake template with unit testing for projects written in C++.

Common Lisp

* `cookiecutter-cl-project`_: A template for Common Lisp project with bootstrap script and Slime integration.


* `cookiecutter-jquery`_: A jQuery plugin project template based on jQuery
* `cookiecutter-jswidget`_: A project template for creating a generic front-end,
non-jQuery JS widget packaged for multiple JS packaging systems.
* `cookiecutter-component`_: A template for a Component JS package.


* `pandoc-talk`_: A cookiecutter template for giving talks with pandoc and XeTeX.


* `slim-berkshelf-vagrant`_: A simple cookiecutter template with sane cookbook defaults for common vagrant/berkshelf cookbooks.


* `cookiecutter-complexity`_: A cookiecutter for a Complexity static site with Bootstrap 3.
* `cookiecutter-tumblr-theme`_: A cookiecutter for a Tumblr theme project with GruntJS as concatination tool.

.. _`cookiecutter-pypackage`:
.. _`@audreyr`:
.. _`cookiecutter-jquery`:
.. _`cookiecutter-flask`:
.. _`cookiecutter-simple-django`:
.. _`cookiecutter-django`:
.. _`cookiecutter-djangopackage`:
.. _`cookiecutter-django-cms`:
.. _`cookiecutter-django-crud`:
.. _`cookiecutter-quokka-module`:
.. _`cookiecutter-django-lborgav`:
.. _`cookiecutter-django-paas`:
.. _`cookiecutter-kivy`:
.. _`cookiecutter-pypackage-minimal`:
.. _`cookiecutter-ansible-role`:
.. _`bootstrap.c`:
.. _`BoilerplatePP`:
.. _`cookiecutter-openstack`:
.. _`cookiecutter-component`:
.. _`cookiecutter-docopt`:
.. _`docopt`:
.. _`cookiecutter-jswidget`:
.. _`pandoc-talk`:
.. _`cookiecutter-complexity`:
.. _`cookiecutter-cl-project`:
.. _`slim-berkshelf-vagrant`:
.. _`cookiecutter-avr`:
.. _`cookiecutter-tumblr-theme`:
.. _`cookiecutter-pylibrary`:
.. _`cookiecutter-pylibrary-minimal`:

Similar projects

* `Paste`_ has a create option that creates a skeleton project.

* `Diecutter`_: an API service that will give you back a configuration file from
a template and variables.

* `Django`_'s `startproject` and `startapp` commands can take in a `--template`

* `python-packager`_: Creates Python packages from its own template, with
configurable options.

* `Yeoman`_ has a Rails-inspired generator system that provides scaffolding
for apps.

* `Pyramid`_'s `pcreate` command for creating Pyramid projects from scaffold templates.

* `mr.bob`_ is a filesystem template renderer, meant to deprecate tools such as
paster and templer.

* `grunt-init`_ used to be built into Grunt and is now a standalone scaffolding tool
to automate project creation.

* `scaffolt`_ consumes JSON generators with Handlebars support.

* `init-skeleton`_ clones or copies a repository, executes npm install and bower install and removes the .git directory.

* `Cog`_ python-based code generation toolkit developed by Ned Batchelder

.. _`Paste`:
.. _`Diecutter`:
.. _`Django`:
.. _`python-packager`:
.. _`Yeoman`:
.. _`Pyramid`:
.. _`mr.bob`:
.. _`grunt-init`:
.. _`scaffolt`:
.. _`init-skeleton`:
.. _`Cog`:


The core committer team is `@audreyr`_, `@pydanny`_, `@michaeljoseph`_, and
`@pfmoore`_. We
welcome you and invite you to participate.

Stuck? Try one of the following:

* See the `Troubleshooting`_ page.
* Ask for help on `Stack Overflow`_.
* You are strongly encouraged to `file an issue`_ about the problem, even if
it's just "I can't get it to work on this cookiecutter" with a link to your
cookiecutter. Don't worry about naming/pinpointing the issue properly.
* Ask for help in #cookiecutter if you must (but please try one of the other
options first, so that others can benefit from the discussion)

Development on Cookiecutter is community-driven:

* Huge thanks to all the `contributors`_ who have pitched in to help make
Cookiecutter an even better tool.
* Everyone is invited to contribute. Read the `contributing instructions`_,
then get started.

Connect with other Cookiecutter contributors and users in IRC:

* #cookiecutter on (note: due to work and commitments,
a core committer might not always be available)

Encouragement is unbelievably motivating. If you want more work done on
Cookiecutter, show support:

* Thank a core committer for their efforts.
* Star `Cookiecutter on GitHub`_.
* Join the `Cookiecutter Gittip community`_.

Got criticism or complaints?

* `File an issue`_ so that Cookiecutter can be improved. Be friendly
and constructive about what could be better. Make detailed suggestions.
* **Keep us in the loop so that we can help.** For example, if you are
discussing problems with Cookiecutter on a mailing list, `file an issue`_
where you link to the discussion thread and/or cc at least 1 core committer on
the email.
* Be encouraging. A comment like "This function ought to be rewritten like
this" is much more likely to result in action than a comment like "Eww, look
how bad this function is."

Waiting for a response to an issue/question?

* Be patient and persistent. All issues are on the core committer team's radar and
will be considered thoughtfully, but we have a lot of issues to work through. If
urgent, it's fine to ping a core committer in the issue with a reminder.
* Ask others to comment, discuss, review, etc.
* Search the Cookiecutter repo for issues related to yours.
* Need a fix/feature/release/help urgently, and can't wait? `@audreyr`_ is
available for hire for consultation or custom development.

.. _`Cookiecutter on GitHub`:
.. _`Troubleshooting`:
.. _`contributors`:
.. _`contributing instructions`:
.. _`Stack Overflow`:
.. _`File an issue`:
.. _`Cookiecutter Gittip community`:
.. _`@pydanny`:
.. _`@michaeljoseph`:
.. _`@pfmoore`:


0.7.2 (2014-08-05)

The goal of this release was to fix cross-platform compatibility, primarily
Windows bugs that had crept in during the addition of new features. As of this
release, Windows is a first-class citizen again, now complete with continuous

Bug Fixes:

* Fixed the contributing file so it displays nicely in Github, thanks to `@pydanny`_.
* Updates 2.6 requirements to include simplejson, thanks to `@saxix`_.
* Avoid unwanted extra spaces in string literal, thanks to `@merwok`_.
* Fix `@unittest.skipIf` error on Python 2.6.
* Let sphinx parse `:param:` properly by inserting newlines #213, thanks to `@mineo`_.
* Fixed Windows test prompt failure by replacing stdin per `@cjrh`_ in #195.
* Made rmtree remove readonly files, thanks to `@pfmoore`_.
* Now using tox to run tests on Appveyor, thanks to `@pfmoore`_ (#241).
* Fixed tests that assumed the system encoding was utf-8, thanks to `@pfmoore`_ (#242, #244).
* Added a tox ini file that uses py.test, thanks to `@pfmoore`_ (#245).

.. _`@merwok`:
.. _`@mineo`:
.. _`@cjrh`:

Other Changes:

* `@audreyr`_ formally accepted position as **BDFL of cookiecutter**.
* Elevated `@pydanny`_, `@michaeljoseph`_, and `@pfmoore`_ to core committer status.
* Added Core Committer guide, by `@audreyr`_.
* Generated apidocs from `make docs`, by `@audreyr`_.
* Added `contributing` command to the `make docs` function, by `@pydanny`_.
* Refactored contributing documentation, included adding core committer instructions, by `@pydanny`_ and `@audreyr`_.
* Do not convert input prompt to bytes, thanks to `@uranusjr`_ (#192).
* Added troubleshooting info about Python 3.3 tests and tox.
* Added documentation about command line arguments, thanks to `@saxix`_.
* Style cleanups.
* Added environment variable to disable network tests for environments without networking, thanks to `@vincentbernat`_.
* Added Appveyor support to aid Windows integrations, thanks to `@pydanny`_ (#215).
* CONTRIBUTING.rst is now generated via `make contributing`, thanks to `@pydanny`_ (#220).
* Removed unnecessary endoing argument to `json.load`, thanks to `@pfmoore`_ (#234).
* Now generating shell hooks dynamically for Unix/Windows portability, thanks to `@pfmoore`_ (#236).
* Removed non-portable assumptions about directory structure, thanks to `@pfmoore`_ (#238).
* Added a note on portability to the hooks documentation, thanks to `@pfmoore`_ (#239).
* Replaced `unicode_open` with direct use of ``, thanks to `@pfmoore`_ (#229).
* Added more Cookiecutters to the list:

* `cookiecutter-kivy`_ by `@hackebrot`_
* BoilerplatePP_ by `@Paspartout`_
* `cookiecutter-pypackage-minimal`_ by `@borntyping`_
* `cookiecutter-ansible-role`_ by `@iknite`_
* `cookiecutter-pylibrary`_ by `@ionelmc`_
* `cookiecutter-pylibrary-minimal`_ by `@ionelmc`_

.. _`cookiecutter-kivy`:
.. _`cookiecutter-ansible-role`:
.. _BoilerplatePP:
.. _`cookiecutter-pypackage-minimal`:
.. _`cookiecutter-pylibrary`:
.. _`cookiecutter-pylibrary-minimal`:

.. _`@michaeljoseph`:
.. _`@iknite`:
.. _`@borntyping`:
.. _`@Paspartout`:
.. _`@pfmoore`:
.. _`@uranusjr`:
.. _`@saxix`:
.. _`@hackebrot`:
.. _`@ionelmc`:

0.7.1 (2014-04-26)

Bug fixes:

* Use the current Python interpreter to run Python hooks, thanks to
* Include tests and documentation in source distribution, thanks to
* Fix various warnings and missing things in the docs (#129, #130),
thanks to `@nedbat`_.
* Add command line option to get version (#89), thanks to `@davedash`_
and `@cyberj`_.

Other changes:

* Add more Cookiecutters to the list:

* `cookiecutter-avr`_ by `@solarnz`_
* `cookiecutter-tumblr-theme`_ by `@relekang`_
* `cookiecutter-django-paas`_ by `@pbacterio`_

.. _`@coderanger`:
.. _`@vincentbernat`:
.. _`@nedbat`:
.. _`@davedash`:
.. _`@cyberj`:

.. _`cookiecutter-avr`:
.. _`@solarnz`:
.. _`cookiecutter-tumblr-theme`:
.. _`@relekang`:
.. _`cookiecutter-django-paas`:
.. _`@pbacterio`:

0.7.0 (2013-11-09)

This is a release with significant improvements and changes. Please read
through this list before you upgrade.

New features:

* Support for --checkout argument, thanks to `@foobacca`_.
* Support for pre-generate and post-generate hooks, thanks to `@raphigaziano`_.
Hooks are Python or shell scripts that run before and/or after your project
is generated.
* Support for absolute paths to cookiecutters, thanks to `@krallin`_.
* Support for Mercurial version control system, thanks to `@pokoli`_.
* When a cookiecutter contains invalid Jinja2 syntax, you get a better message
that shows the location of the TemplateSyntaxError. Thanks to `@benjixx`_.
* Can now prompt the user to enter values during generation from a local
cookiecutter, thanks to `@ThomasChiroux`_. This is now always the default
behavior. Prompts can also be supressed with `--no-input`.
* Your cloned cookiecutters are stored by default in your `~/.cookiecutters/`
directory (or Windows equivalent). The location is configurable. (This is a
major change from the pre-0.7.0 behavior, where cloned cookiecutters were
deleted at the end of project generation.) Thanks `@raphigaziano`_.
* User config in a `~/.cookiecutterrc` file, thanks to `@raphigaziano`_.
Configurable settings are `cookiecutters_dir` and `default_context`.
* File permissions are now preserved during project generation, thanks to

Bug fixes:

* Unicode issues with prompts and answers are fixed, thanks to `@s-m-i-t-a`_.
* The test suite now runs on Windows, which was a major effort. Thanks to
`@pydanny`_, who collaborated on this with me.

Other changes:

* Quite a bit of refactoring and API changes.
* Lots of documentation improvements. Thanks `@sloria`_, `@alex`_, `@pydanny`_,
`@freakboy3742`_, `@es128`_, `@rolo`_.
* Better naming and organization of test suite.
* A `CookiecutterCleanSystemTestCase` to use for unit tests affected by the
user's config and cookiecutters directory.
* Improvements to the project's Makefile.
* Improvements to tests. Thanks `@gperetin`_, `@s-m-i-t-a`_.
* Removal of `subprocess32` dependency. Now using non-context manager version
of `subprocess.Popen` for Python 2 compatibility.
* Removal of cookiecutter's `cleanup` module.
* A bit of `` cleanup, thanks to `@oubiga`_.
* Now depends on binaryornot 0.2.0.

.. _`@foobacca`:
.. _`@raphigaziano`:
.. _`@gperetin`:
.. _`@krallin`:
.. _`@pokoli`:
.. _`@benjixx`:
.. _`@ThomasChiroux`:
.. _`@s-m-i-t-a`:
.. _`@sloria`:
.. _`@alex`:
.. _`@freakboy3742`:
.. _`@es128`:
.. _`@rolo`:
.. _`@oubiga`:

0.6.4 (2013-08-21)

* Windows support officially added.
* Fix TemplateNotFound Exception on Windows (#37).

0.6.3 (2013-08-20)

* Fix copying of binary files in nested paths (#41), thanks to `@sloria`_.

.. _`@sloria`:

0.6.2 (2013-08-19)

* Depend on Jinja2>=2.4 instead of Jinja2==2.7.
* Fix errors on attempt to render binary files. Copy them over from the project
template without rendering.
* Fix Python 2.6/2.7 `UnicodeDecodeError` when values containing Unicode chars
are in `cookiecutter.json`.
* Set encoding in Python 3 `unicode_open()` to always be utf-8.

0.6.1 (2013-08-12)

* Improved project template finding. Now looks for the occurrence of `{{`,
`cookiecutter`, and `}}` in a directory name.
* Fix help message for input_dir arg at command prompt.
* Minor edge cases found and corrected, as a result of improved test coverage.

0.6.0 (2013-08-08)

* Config is now in a single `cookiecutter.json` instead of in `json/`.
* When you create a project from a git repo template, Cookiecutter prompts
you to enter custom values for the fields defined in `cookiecutter.json`.

0.5 (2013-07-28)

* Friendlier, more simplified command line usage::

# Create project from the cookiecutter-pypackage/ template
$ cookiecutter cookiecutter-pypackage/

# Create project from the cookiecutter-pypackage.git repo template
$ cookiecutter

* Can now use Cookiecutter from Python as a package::

from cookiecutter.main import cookiecutter

# Create project from the cookiecutter-pypackage/ template

# Create project from the cookiecutter-pypackage.git repo template

* Internal refactor to remove any code that changes the working directory.

0.4 (2013-07-22)

* Only takes in one argument now: the input directory. The output directory
is generated by rendering the name of the input directory.
* Output directory cannot be the same as input directory.

0.3 (2013-07-17)

* Takes in command line args for the input and output directories.

0.2.1 (2013-07-17)

* Minor cleanup.

0.2 (2013-07-17)

Bumped to "Development Status :: 3 - Alpha".

* Works with any type of text file.
* Directory names and filenames can be templated.

0.1.0 (2013-07-11)

* First release on PyPI.

File Type Py Version Uploaded on Size
cookiecutter-0.7.2.tar.gz (md5) Source 2014-08-06 104KB