cookiecutter package


cookiecutter.cli module


Main cookiecutter CLI.

cookiecutter.cli.validate_extra_context(ctx, param, value)[source]

Returns the Cookiecutter version, location and Python powering it.

cookiecutter.config module


Global configuration handling


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

cookiecutter.config.get_user_config(config_file=None, default_config=False)[source]

Return the user config as a dict.

If default_config is True, ignore ``config_file and return default values for the config parameters.

If a path to a config_file is given, that is different from the default location, load the user config from that.

Otherwise look up the config file path in the COOKIECUTTER_CONFIG environment variable. If set, load the config from this path. This will raise an error if the specified path is not valid.

If the environment variable is not set, try the default config file path before falling back to the default config values.

cookiecutter.environment module

Jinja2 environment and extensions loading.

class cookiecutter.environment.ExtensionLoaderMixin(**kwargs)[source]

Bases: object

Mixin providing sane loading of extensions specified in a given context.

The context is being extracted from the keyword arguments before calling the next parent class in line of the child.

class cookiecutter.environment.StrictEnvironment(**kwargs)[source]

Bases: cookiecutter.environment.ExtensionLoaderMixin, jinja2.environment.Environment

Create strict Jinja2 environment.

Jinja2 environment will raise error on undefined variable in template- rendering context.

cookiecutter.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.ContextDecodingException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a project’s JSON context file can not be decoded.

exception cookiecutter.exceptions.CookiecutterException[source]

Bases: exceptions.Exception

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

exception cookiecutter.exceptions.FailedHookException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a hook script fails

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.InvalidModeException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when cookiecutter is called with both no_input==True and replay==True at the same time.

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.OutputDirExistsException[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when the output directory of the project exists already.

exception cookiecutter.exceptions.RepositoryCloneFailed[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a cookiecutter template can’t be cloned.

exception cookiecutter.exceptions.RepositoryNotFound[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when the specified cookiecutter repository doesn’t exist.

exception cookiecutter.exceptions.UndefinedVariableInTemplate(message, error, context)[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when a template uses a variable which is not defined in the context.

exception cookiecutter.exceptions.UnknownExtension[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised when an environment is unable to import a required extension.

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.

exception cookiecutter.exceptions.VCSNotInstalled[source]

Bases: cookiecutter.exceptions.CookiecutterException

Raised if the version control system (git or hg) is not installed.

cookiecutter.find module

Functions for finding Cookiecutter templates and other components.


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

cookiecutter.generate module

Functions for generating a project from a project template.

cookiecutter.generate.apply_overwrites_to_context(context, overwrite_context)[source]

Modify the given context in place based on the overwrite_context.


Ensure that dirname is a templated directory name.

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

Generate 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.
  • default_context – Dictionary containing config to take into account.
  • extra_context – Dictionary containing configuration overrides
cookiecutter.generate.generate_file(project_dir, infile, context, env)[source]

Render filename of infile as name of outfile, handle infile correctly.

Dealing 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'.', overwrite_if_exists=False)[source]

Render 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.
  • overwrite_if_exists – Overwrite the contents of the output directory if it exists.
cookiecutter.generate.is_copy_only_path(path, context)[source]

Check whether the given path should only be copied as opposed to being rendered.

Returns True if path matches a pattern in the given context dict, otherwise False.

  • path – A file-system path referring to a file or dir that should be rendered or just copied.
  • context – cookiecutter context.
cookiecutter.generate.render_and_create_dir(dirname, context, output_dir, environment, overwrite_if_exists=False)[source]

Render name of a directory, create the directory, return its path.

cookiecutter.hooks module

Functions for discovering and executing various cookiecutter hooks.

cookiecutter.hooks.find_hook(hook_name, hooks_dir='hooks')[source]

Return a dict of all hook scripts provided.

Must be called with the project template as the current working directory. 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.

  • hook_name – The hook to find
  • hooks_dir – The hook directory in the template

The absolute path to the hook script or None

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

Try to find and execute a hook from the specified project directory.

  • hook_name – The hook to execute.
  • project_dir – The directory to execute the script from.
  • context – Cookiecutter project context.
cookiecutter.hooks.run_script(script_path, cwd='.')[source]

Execute a script from a working directory.

  • script_path – Absolute path to the script to run.
  • cwd – The directory to run the script from.
cookiecutter.hooks.run_script_with_context(script_path, cwd, context)[source]

Execute a script after rendering it with Jinja.

  • script_path – Absolute path to the script to run.
  • cwd – The directory to run the script from.
  • context – Cookiecutter project template context.
cookiecutter.hooks.valid_hook(hook_file, hook_name)[source]

Determine if a hook file is valid.

  • hook_file – The hook file to consider for validity
  • hook_name – The hook to find

The hook file validity

cookiecutter.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(template, checkout=None, no_input=False, extra_context=None, replay=False, overwrite_if_exists=False, output_dir=u'.', config_file=None, default_config=False)[source]

API equivalent to using Cookiecutter at the command line.

  • template – A directory containing a project template directory, or a URL to a git repository.
  • checkout – The branch, tag or commit ID to checkout after clone.
  • no_input – Prompt the user at command line for manual configuration?
  • extra_context – A dictionary of context that overrides default and user configuration.
  • output_dir – Where to output the generated project dir into.
  • config_file – User configuration file path.
  • default_config – Use default values rather than a config file.

overwrite_if_exists: Overwrite the contents of output directory if it exists

cookiecutter.prompt module


Functions for prompting the user for project info.

cookiecutter.prompt.prompt_choice_for_config(cookiecutter_dict, env, key, options, no_input)[source]

Prompt the user which option to choose from the given. Each of the possible choices is rendered beforehand.

cookiecutter.prompt.prompt_for_config(context, no_input=False)[source]

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

Parameters:no_input – Prompt the user at command line for manual configuration?
cookiecutter.prompt.read_user_choice(var_name, options)[source]

Prompt the user to choose from several options for the given variable.

The first item will be returned if no input happens.

  • var_name (str) – Variable as specified in the context
  • options (list) – Sequence of options that are available to select from

Exactly one item of options that has been chosen by the user

cookiecutter.prompt.read_user_dict(var_name, default_value)[source]

Prompt the user to provide a dictionary of data.

  • var_name (str) – Variable as specified in the context
  • default_value – Value that will be returned if no input is provided

A Python dictionary to use in the context.

cookiecutter.prompt.read_user_variable(var_name, default_value)[source]

Prompt the user for the given variable and return the entered value or the given default.

  • var_name (str) – Variable of the context to query the user
  • default_value – Value that will be returned if no input happens
cookiecutter.prompt.read_user_yes_no(question, default_value)[source]

Prompt the user to reply with ‘yes’ or ‘no’ (or equivalent values).

Possible choices are ‘true’, ‘1’, ‘yes’, ‘y’ or ‘false’, ‘0’, ‘no’, ‘n’
  • question (str) – Question to the user
  • default_value – Value that will be returned if no input happens
cookiecutter.prompt.render_variable(env, raw, cookiecutter_dict)[source]

Inside the prompting taken from the cookiecutter.json file, this renders the next variable. For example, if a project_name is “Peanut Butter Cookie”, the repo_name could be be rendered with:

{{ cookiecutter.project_name.replace(” ”, “_”) }}.

This is then presented to the user as the default.

  • env (Environment) – A Jinja2 Environment object.
  • raw (str) – The next value to be prompted for by the user.
  • cookiecutter_dict (dict) – The current context as it’s gradually being populated with variables.

The rendered value for the default variable.

cookiecutter.replay module


cookiecutter.replay.dump(replay_dir, template_name, context)[source]
cookiecutter.replay.get_file_name(replay_dir, template_name)[source]
cookiecutter.replay.load(replay_dir, template_name)[source]

cookiecutter.repository module

Cookiecutter repository functions.

cookiecutter.repository.determine_repo_dir(template, abbreviations, clone_to_dir, checkout, no_input)[source]

Locate the repository directory from a template reference.

Applies repository abbreviations to the template reference. If the template refers to a repository URL, clone it. If the template is a path to a local repository, use it.

  • template – A directory containing a project template directory, or a URL to a git repository.
  • abbreviations – A dictionary of repository abbreviation definitions.
  • clone_to_dir – The directory to clone the repository into.
  • checkout – The branch, tag or commit ID to checkout after clone.
  • no_input – Prompt the user at command line for manual configuration?

The cookiecutter template directory


RepositoryNotFound if a repository directory could not be found.

cookiecutter.repository.expand_abbreviations(template, abbreviations)[source]

Expand abbreviations in a template name.

  • template – The project template name.
  • abbreviations – Abbreviation definitions.

Return True if value is a repository URL.


Determine if repo_directory contains a cookiecutter.json file.

Parameters:repo_directory – The candidate repository directory.
Returns:True if the repo_directory is valid, else False.

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


Makes script_path executable

Parameters:script_path – The file to change

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.

cookiecutter.vcs module

Helper functions for working with version control systems.

cookiecutter.vcs.clone(repo_url, checkout=None, clone_to_dir=u'.', no_input=False)[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.
  • clone_to_dir – The directory to clone to. Defaults to the current directory.
  • no_input – Suppress all user prompts when calling via API.

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

Repos can be identified by prepending “hg+” or “git+” to the repo URL.

Parameters:repo_url – Repo URL of unknown type.
Returns:(‘git’, repo_url), (‘hg’, repo_url), or None.

Check if the version control system for a repo type is installed.

cookiecutter.vcs.prompt_and_delete_repo(repo_dir, no_input=False)[source]

Ask the user whether it’s okay to delete the previously-cloned repo.

If yes, deletes it. Otherwise, Cookiecutter exits.

  • repo_dir – Directory of previously-cloned repo.
  • no_input – Suppress prompt to delete repo and just delete it.

Module contents


Main package for Cookiecutter.