0
# Cookiecutter
1
2
A command-line utility that creates projects from project templates (cookiecutters). Cookiecutter enables developers to quickly generate project structures by answering a few questions about their project, making it ideal for scaffolding Python packages, web applications, and other software projects.
3
4
## Package Information
5
6
- **Package Name**: cookiecutter
7
- **Package Type**: CLI utility and Python library
8
- **Language**: Python
9
- **Installation**: `pip install cookiecutter` or `pipx install cookiecutter`
10
11
## Core Imports
12
13
```python
14
from cookiecutter.main import cookiecutter
15
```
16
17
For CLI usage:
18
```python
19
from cookiecutter.cli import main
20
```
21
22
## Basic Usage
23
24
### Command Line Usage
25
26
```bash
27
# Create project from GitHub template
28
cookiecutter gh:audreyfeldroy/cookiecutter-pypackage
29
30
# Create project from local template
31
cookiecutter ./my-template-directory/
32
33
# Create project with no user input (use defaults)
34
cookiecutter template_path --no-input
35
36
# Create project with extra context
37
cookiecutter template_path --no-input key1=value1 key2=value2
38
```
39
40
### Programmatic Usage
41
42
```python
43
from cookiecutter.main import cookiecutter
44
45
# Create project from local template
46
result = cookiecutter('cookiecutter-pypackage/')
47
48
# Create project from remote template with extra context
49
result = cookiecutter(
50
'gh:audreyfeldroy/cookiecutter-pypackage',
51
extra_context={'project_name': 'my-awesome-project', 'author': 'Jane Doe'},
52
no_input=True
53
)
54
55
# Create project with custom output directory
56
result = cookiecutter(
57
'template-path',
58
output_dir='/path/to/projects',
59
overwrite_if_exists=True
60
)
61
```
62
63
## Architecture
64
65
Cookiecutter's architecture centers around template processing and user interaction:
66
67
- **Template Discovery**: Locates and validates cookiecutter templates from local directories, Git repositories, or zip files
68
- **Context Generation**: Processes `cookiecutter.json` files to generate template variables and prompts
69
- **User Interaction**: Prompts users for template variable values with support for various input types
70
- **Template Rendering**: Uses Jinja2 to render template files and directory names with user-provided context
71
- **Hook System**: Executes pre/post generation scripts for custom setup logic
72
- **Repository Management**: Handles cloning, extracting, and caching of remote templates
73
74
This design enables maximum flexibility for template creators while providing a consistent, user-friendly interface for project generation.
75
76
## Capabilities
77
78
### Main API
79
80
Core functionality for generating projects from templates, including the primary `cookiecutter()` function and CLI interface.
81
82
```python { .api }
83
def cookiecutter(
84
template,
85
checkout=None,
86
no_input=False,
87
extra_context=None,
88
replay=None,
89
overwrite_if_exists=False,
90
output_dir='.',
91
config_file=None,
92
default_config=False,
93
password=None,
94
directory=None,
95
skip_if_file_exists=False,
96
accept_hooks=True,
97
keep_project_on_failure=False
98
): ...
99
```
100
101
[Main API](./main-api.md)
102
103
### Configuration Management
104
105
User configuration handling with defaults, file-based config, and runtime overrides for customizing cookiecutter behavior.
106
107
```python { .api }
108
def get_user_config(config_file=None, default_config=False): ...
109
def get_config(config_path): ...
110
def merge_configs(default, overwrite): ...
111
```
112
113
[Configuration](./configuration.md)
114
115
### Template Processing
116
117
Context generation, file rendering, and template discovery functionality that powers cookiecutter's core template processing capabilities.
118
119
```python { .api }
120
def generate_context(context_file='cookiecutter.json', default_context=None, extra_context=None): ...
121
def generate_files(repo_dir, context=None, output_dir='.', overwrite_if_exists=False, skip_if_file_exists=False, accept_hooks=True, keep_project_on_failure=False): ...
122
def find_template(repo_dir, env): ...
123
```
124
125
[Template Processing](./template-processing.md)
126
127
### Repository Handling
128
129
Support for Git repositories, zip files, and URL-based templates with automatic cloning, extraction, and local caching.
130
131
```python { .api }
132
def determine_repo_dir(template, abbreviations, clone_to_dir, checkout, no_input, password=None, directory=None): ...
133
def clone(repo_url, checkout=None, clone_to_dir=".", no_input=False): ...
134
def unzip(zip_uri, is_url, clone_to_dir=".", no_input=False, password=None): ...
135
```
136
137
[Repository Handling](./repository-handling.md)
138
139
### User Interaction
140
141
Interactive prompts for template variables with support for different input types including text, choices, boolean, and JSON inputs.
142
143
```python { .api }
144
def prompt_for_config(context, no_input=False): ...
145
def read_user_variable(var_name, default_value, prompts=None, prefix=""): ...
146
def read_user_choice(var_name, options, prompts=None, prefix=""): ...
147
```
148
149
[User Interaction](./user-interaction.md)
150
151
### Hooks and Extensions
152
153
Pre/post generation hook system and Jinja2 template extensions for enhanced templating capabilities.
154
155
```python { .api }
156
def run_hook(hook_name, project_dir, context): ...
157
def run_pre_prompt_hook(repo_dir): ...
158
class JsonifyExtension(Extension): ...
159
class SlugifyExtension(Extension): ...
160
```
161
162
[Hooks and Extensions](./hooks-extensions.md)
163
164
### Utilities and Exceptions
165
166
Helper functions, logging configuration, replay functionality, and comprehensive exception hierarchy.
167
168
```python { .api }
169
def rmtree(path): ...
170
def make_sure_path_exists(path): ...
171
def configure_logger(stream_level='DEBUG', debug_file=None): ...
172
class CookiecutterException(Exception): ...
173
```
174
175
[Utilities and Exceptions](./utilities-exceptions.md)
176
177
## Version Information
178
179
```python { .api }
180
__version__: str # Package version string (access via cookiecutter.__version__)
181
```
182
183
### Usage
184
```python
185
import cookiecutter
186
print(cookiecutter.__version__) # e.g., "2.6.0"
187
```