skip to navigation
skip to content

cookiecutter 0.7.1

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-flask-env`_: A lucuma-flavored flask app template.
* `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..


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

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-flask-env`:
.. _`cookiecutter-simple-django`:
.. _`cookiecutter-django`:
.. _`cookiecutter-djangopackage`:
.. _`cookiecutter-django-cms`:
.. _`cookiecutter-django-crud`:
.. _`cookiecutter-quokka-module`:
.. _`cookiecutter-django-lborgav`:
.. _`cookiecutter-django-paas`:
.. _`bootstrap.c`:
.. _`cookiecutter-openstack`:
.. _`cookiecutter-component`:
.. _`cookiecutter-docopt`:
.. _`docopt`:
.. _`cookiecutter-jswidget`:
.. _`pandoc-talk`:
.. _`cookiecutter-complexity`:
.. _`cookiecutter-cl-project`:
.. _`slim-berkshelf-vagrant`:
.. _`cookiecutter-avr`:
.. _`cookiecutter-tumblr-theme`:

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.

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


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,
`@audreyr`_ might not always be available)

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

* Star `Cookiecutter on GitHub`_.
* Please, please 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 `` 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 `audreyr`_'s radar and will be
considered thoughtfully, but due to the growing to-do list/free time ratio,
it may take time for a response. If urgent, it's fine to ping `audreyr`_
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 hourly for consultation or custom development.

.. _`Cookiecutter on GitHub`:
.. _`Troubleshooting`:
.. _`contributors`:
.. _`contributing instructions`:
.. _`Stack Overflow`:
.. _`File an issue`:
.. _`Cookiecutter Gittip community`:
.. _`audreyr`:


In Development (Master Branch)

Nothing yet.

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`:
.. _`@pydanny`:
.. _`@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.


If something is not listed here, check the `issues under each milestone`_.

This is subject to change depending on the needs and contributions of the
community. Feedback on pull requests/issues affects the priority of items on
the roadmap.

Also, please be patient and keep in mind that this is a volunteer effort, and
that the review process takes time.

.. _`issues under each milestone`:


This is a patch release to fix minor bugs and any potential problems with 0.7.0.

* Various README enhancements.


This release will include a number of features and bug fixes proposed and
implemented by the community in pull requests.



This release is for new features proposed through issues. Note: some issues
tagged 0.9.0 might be moved to 0.8.0 if anyone implements them and submits a
pull request.

* Support for alternate config location as per XDG Base Directory Spec
* TODO  
File Type Py Version Uploaded on Size
cookiecutter-0.7.1.tar.gz (md5) Source 2014-04-26 93KB