skip to navigation
skip to content

Not Logged In

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.0.0

=============
Cookiecutter
=============

.. image:: https://badge.fury.io/py/cookiecutter.png
:target: http://badge.fury.io/py/cookiecutter

.. image:: https://travis-ci.org/audreyr/cookiecutter.png?branch=master
:target: https://travis-ci.org/audreyr/cookiecutter

.. image:: https://pypip.in/d/cookiecutter/badge.png
:target: https://crate.io/packages/cookiecutter?version=latest

.. image:: https://coveralls.io/repos/audreyr/cookiecutter/badge.png?branch=master
:target: https://coveralls.io/r/audreyr/cookiecutter?branch=master


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: http://cookiecutter.rtfd.org
* GitHub: https://github.com/audreyr/cookiecutter
* Free software: BSD license
* PyPI: https://pypi.python.org/pypi/cookiecutter

.. image:: https://raw.github.com/audreyr/cookiecutter/aa309b73bdc974788ba265d843a65bb94c2e608e/cookiecutter_medium.png

Features
--------

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 https://github.com/audreyr/cookiecutter-pypackage.git

* 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
cookiecutter('cookiecutter-pypackage/')

# Create project from the cookiecutter-pypackage.git repo template
cookiecutter('https://github.com/audreyr/cookiecutter-pypackage.git')

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

{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}/{{cookiecutter.repo_name}}.py

* 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": "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"
}

* 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

default_context:
full_name: "Audrey Roy"
email: "audreyr@gmail.com"
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!

Python
~~~~~~

* `cookiecutter-pypackage`_: `@audreyr`_'s ultimate Python package project
template.
* `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..

C
~~

* `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.

JS
~~

* `cookiecutter-jquery`_: A jQuery plugin project template based on jQuery
Boilerplate.
* `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.

LaTeX/XeTeX
~~~~~~~~~~~

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


Berkshelf-Vagrant
~~~~~~~~~~~~~~~~~

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


HTML
~~~~

* `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`: https://github.com/audreyr/cookiecutter-pypackage
.. _`@audreyr`: https://github.com/audreyr/
.. _`cookiecutter-jquery`: https://github.com/audreyr/cookiecutter-jquery
.. _`cookiecutter-flask`: https://github.com/sloria/cookiecutter-flask
.. _`cookiecutter-flask-env`: https://github.com/lucuma/cookiecutter-flask-env
.. _`cookiecutter-simple-django`: https://github.com/marcofucci/cookiecutter-simple-django
.. _`cookiecutter-django`: https://github.com/pydanny/cookiecutter-django
.. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage
.. _`cookiecutter-django-cms`: https://github.com/palazzem/cookiecutter-django-cms
.. _`cookiecutter-django-crud`: https://github.com/wildfish/cookiecutter-django-crud
.. _`cookiecutter-quokka-module`: https://github.com/pythonhub/cookiecutter-quokka-module
.. _`cookiecutter-django-lborgav`: https://github.com/lborgav/cookiecutter-django
.. _`cookiecutter-django-paas`: https://github.com/pbacterio/cookiecutter-django-paas
.. _`bootstrap.c`: https://github.com/vincentbernat/bootstrap.c
.. _`cookiecutter-openstack`: https://github.com/openstack-dev/cookiecutter
.. _`cookiecutter-component`: https://github.com/audreyr/cookiecutter-component
.. _`cookiecutter-docopt`: https://github.com/sloria/cookiecutter-docopt
.. _`docopt`: http://docopt.org/
.. _`cookiecutter-jswidget`: https://github.com/audreyr/cookiecutter-jswidget
.. _`pandoc-talk`: https://github.com/larsyencken/pandoc-talk
.. _`cookiecutter-complexity`: https://github.com/audreyr/cookiecutter-complexity
.. _`cookiecutter-cl-project`: https://github.com/svetlyak40wt/cookiecutter-cl-project
.. _`slim-berkshelf-vagrant`: https://github.com/mahmoudimus/cookiecutter-slim-berkshelf-vagrant
.. _`cookiecutter-avr`: https://github.com/solarnz/cookiecutter-avr
.. _`cookiecutter-tumblr-theme`: https://github.com/relekang/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`
option.

* `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`: http://pythonpaste.org/script/#paster-create
.. _`Diecutter`: https://github.com/novagile/diecutter
.. _`Django`: https://docs.djangoproject.com/en/1.5/ref/django-admin/#django-admin-startproject
.. _`python-packager`: https://github.com/fcurella/python-packager
.. _`Yeoman`: https://github.com/yeoman/generator
.. _`Pyramid`: http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/scaffolding.html
.. _`mr.bob`: https://github.com/iElectric/mr.bob
.. _`grunt-init`: https://github.com/gruntjs/grunt-init
.. _`scaffolt`: https://github.com/paulmillr/scaffolt
.. _`init-skeleton`: https://github.com/paulmillr/init-skeleton

Community
---------

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 irc.freenode.net (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 `audreyr@gmail.com` 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`: https://github.com/audreyr/cookiecutter
.. _`Troubleshooting`: http://cookiecutter.readthedocs.org/en/latest/troubleshooting.html
.. _`contributors`: https://github.com/audreyr/cookiecutter/blob/master/AUTHORS.rst
.. _`contributing instructions`: https://github.com/audreyr/cookiecutter/blob/master/CONTRIBUTING.rst
.. _`Stack Overflow`: http://stackoverflow.com/
.. _`File an issue`: https://github.com/audreyr/cookiecutter/issues?state=open
.. _`Cookiecutter Gittip community`: https://www.gittip.com/for/cookiecutter/
.. _`audreyr`: https://github.com/audreyr




History
-------

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
`@coderanger`_.
* Include tests and documentation in source distribution, thanks to
`@vincentbernat`_.
* 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`: https://github.com/coderanger
.. _`@vincentbernat`: https://github.com/vincentbernat
.. _`@nedbat`: https://github.com/nedbat
.. _`@davedash`: https://github.com/davedash
.. _`@cyberj`: https://github.com/cyberj

.. _`cookiecutter-avr`: https://github.com/solarnz/cookiecutter-avr
.. _`@solarnz`: https://github.com/solarnz
.. _`cookiecutter-tumblr-theme`: https://github.com/relekang/cookiecutter-tumblr-theme
.. _`@relekang`: https://github.com/relekang
.. _`cookiecutter-django-paas`: https://github.com/pbacterio/cookiecutter-django-paas
.. _`@pbacterio`: https://github.com/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
`@benjixx`_.

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 `setup.py` cleanup, thanks to `@oubiga`_.
* Now depends on binaryornot 0.2.0.

.. _`@foobacca`: https://github.com/foobacca/
.. _`@raphigaziano`: https://github.com/raphigaziano/
.. _`@gperetin`: https://github.com/gperetin/
.. _`@krallin`: https://github.com/krallin/
.. _`@pokoli`: https://github.com/pokoli/
.. _`@benjixx`: https://github.com/benjixx/
.. _`@ThomasChiroux`: https://github.com/ThomasChiroux/
.. _`@s-m-i-t-a`: https://github.com/s-m-i-t-a/
.. _`@sloria`: https://github.com/sloria/
.. _`@alex`: https://github.com/alex/
.. _`@pydanny`: https://github.com/pydanny/
.. _`@freakboy3742`: https://github.com/freakboy3742/
.. _`@es128`: https://github.com/es128/
.. _`@rolo`: https://github.com/rolo/
.. _`@oubiga`: https://github.com/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`: https://github.com/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 https://github.com/audreyr/cookiecutter-pypackage.git

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

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/audreyr/cookiecutter-pypackage.git')

* 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.

Roadmap
-------

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`: https://github.com/audreyr/cookiecutter/issues/milestones

0.7.1
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

* Various README enhancements.
* TODO

0.8.0
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

* TODO

0.9.0
~~~~~~~~~~~~~~~~~~~~~~~~~~

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
  • Downloads (All Versions):
  • 203 downloads in the last day
  • 1421 downloads in the last week
  • 5480 downloads in the last month