cookiecutter Package

cookiecutter Package


Main package for Cookiecutter.

config Module


Global configuration handling


Retrieve the config from the specified path, returning it as a config dict.


Retrieve config from the user’s ~/.cookiecutterrc, if it exists. Otherwise, return None.

exceptions Module


All exceptions used in the Cookiecutter code base are defined here.

exception cookiecutter.exceptions.ConfigDoesNotExistException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when get_config() is passed a path to a config file, but no file is found at that path.

exception cookiecutter.exceptions.CookiecutterException[source]

Bases: exceptions.Exception

Base exception class. All Cookiecutter-specific exceptions should subclass this class.

exception cookiecutter.exceptions.InvalidConfiguration[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised if the global configuration file is not valid YAML or is badly contructed.

exception cookiecutter.exceptions.MissingProjectDir[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised during cleanup when remove_repo() can’t find a generated project directory inside of a repo.

exception cookiecutter.exceptions.NonTemplatedInputDirException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a project’s input dir is not templated. The name of the input directory should always contain a string that is rendered to something else, so that input_dir != output_dir.

exception cookiecutter.exceptions.UnknownRepoType[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised if a repo’s type cannot be determined.

exception cookiecutter.exceptions.UnknownTemplateDirException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when Cookiecutter cannot determine which directory is the project template, e.g. more than one dir appears to be a template dir.

find Module


Functions for finding Cookiecutter templates and other components.


Determines which child directory of repo_dir is the project template.

Parameters:repo_dir – Local directory of newly cloned repo.
Returns project_template:
 Relative path to project template.

generate Module


Functions for generating a project from a project template.


Ensures that dirname is a templated directory name.

cookiecutter.generate.generate_context(context_file=u'cookiecutter.json', default_context=None)[source]

Generates the context for a Cookiecutter project template. Loads the JSON file as a Python object, with key being the JSON filename.

  • context_file – JSON file containing key/value pairs for populating the cookiecutter’s variables.
  • config_dict – Dict containing any config to take into account.
cookiecutter.generate.generate_file(project_dir, infile, context, env)[source]
  1. Render the filename of infile as the name of outfile.

  2. Deal with infile appropriately:

    1. If infile is a binary file, copy it over without rendering.
    2. If infile is a text file, render its contents and write the rendered infile to outfile.


When calling generate_file(), the root template dir must be the current working directory. Using utils.work_in() is the recommended way to perform this directory change.
  • project_dir – Absolute path to the resulting generated project.
  • infile – Input file to generate the file from. Relative to the root template dir.
  • context – Dict for populating the cookiecutter’s variables.
  • env – Jinja2 template execution environment.
cookiecutter.generate.generate_files(repo_dir, context=None, output_dir=u'.')[source]

Renders the templates and saves them to files.

  • repo_dir – Project template input directory.
  • context – Dict for populating the template’s variables.
  • output_dir – Where to output the generated project dir into.
cookiecutter.generate.render_and_create_dir(dirname, context, output_dir)[source]

Renders the name of a directory, creates the directory, and returns its path.

hooks Module


Functions for discovering and executing various cookiecutter hooks.


Must be called with the project template as the current working directory. Returns a dict of all hook scripts provided. Dict’s key will be the hook/script’s name, without extension, while values will be the absolute path to the script. Missing scripts will not be included in the returned dict.

cookiecutter.hooks.run_hook(hook_name, project_dir)[source]

Try and find a script mapped to hook_name in the current working directory, and execute it from project_dir.

main Module


Main entry point for the cookiecutter command.

The code in this module is also a good example of how to use Cookiecutter as a library rather than a script.

cookiecutter.main.cookiecutter(input_dir, checkout=None, no_input=False)[source]

API equivalent to using Cookiecutter at the command line.

  • input_dir – A directory containing a project template dir, or a URL to git repo.
  • checkout – The branch, tag or commit ID to checkout after clone

Entry point for the package, as defined in


Parse the command-line arguments to Cookiecutter.

prompt Module


Functions for prompting the user for project info.


Prompts the user to enter new config, using context as a source for the field names and sample values.

cookiecutter.prompt.query_yes_no(question, default=u'yes')[source]

Ask a yes/no question via raw_input() and return their answer.

  • question – A string that is presented to the user.
  • default – The presumed answer if the user just hits <Enter>. It must be “yes” (the default), “no” or None (meaning an answer is required of the user).

The “answer” return value is one of “yes” or “no”.

Adapted from

utils Module


Helper functions used throughout Cookiecutter.

cookiecutter.utils.force_delete(func, path, exc_info)[source]

Error handler for shutil.rmtree() equivalent to rm -rf Usage: shutil.rmtree(path, onerror=force_delete) From


Ensures that a directory exists.

Parameters:path – A directory path.

Removes a directory and all its contents. Like rm -rf on Unix.

Parameters:path – A directory path.
cookiecutter.utils.work_in(*args, **kwds)[source]

Context manager version of os.chdir. When exited, returns to the working directory prior to entering.

vcs Module


Helper functions for working with version control systems.

cookiecutter.vcs.clone(repo_url, checkout=None, clone_to_dir=u'.')[source]

Clone a repo to the current directory.

  • repo_url – Repo URL of unknown type.
  • checkout – The branch, tag or commit ID to checkout after clone

Determines if repo_url should be treated as a URL to a git or hg repo.

Parameters:repo_url – Repo URL of unknown type.
Returns:“git”, “hg”, or None.

Asks the user whether it’s okay to delete the previously-cloned repo. If yes, deletes it. Otherwise, Cookiecutter exits.

Parameters:repo_dir – Directory of previously-cloned repo.