Creating Your Own Template

July 6, 2026 · View on GitHub

Complete tutorial for creating a cookiecutter template from scratch.

Goal

We will create a cookiecutter-python-package template that generates a Python package with setup.py, pyproject.toml, pytest tests, GitHub Actions CI, README, LICENSE, and optional Docker support.

Step 1: Initial Structure

mkdir cookiecutter-python-package
cd cookiecutter-python-package

cookiecutter-python-package/
├── cookiecutter.json
├── _copy_without_render
├── hooks/
│   ├── pre_gen_project.py
│   └── post_gen_project.py
├── {{ cookiecutter.project_name }}/
│   ├── README.md
│   ├── LICENSE
│   ├── .gitignore
│   ├── setup.py
│   ├── pyproject.toml
│   ├── {{ cookiecutter.pkg_name }}/
│   │   └── __init__.py
│   ├── tests/
│   │   └── test_{{ cookiecutter.pkg_name }}.py
│   ├── .github/workflows/ci.yml
│   └── Dockerfile
└── README.md

Step 2: `cookiecutter.json`

{
  "project_name": "My Python Package",
  "project_slug": "{{ cookiecutter.project_name|lower|replace(' ', '_')|replace('-', '_') }}",
  "pkg_name": "{{ cookiecutter.project_slug|replace('_', '') }}",
  "repo_name": "{{ cookiecutter.project_name|lower|replace(' ', '-') }}",
  "author_name": "Your Name",
  "author_email": "you@example.com",
  "github_username": "yourusername",
  "version": "0.1.0",
  "python_version": "3.11",
  "license": ["MIT", "BSD-3-Clause", "Apache-2.0", "GPLv3", "proprietary"],
  "use_docker": ["no", "yes"],
  "use_ci": ["no", "github", "gitlab"]
}

Derived variables (project_slug, pkg_name, repo_name) are computed with Jinja2 and not shown in the prompt.

Step 3: Template Files

`README.md`

# {{ cookiecutter.project_name }}

{{ cookiecutter.project_name }} — a Python package.

## Installation

```bash
pip install {{ cookiecutter.pkg_name }}

License

{{ cookiecutter.license }} — {{ cookiecutter.author_name }}


### `setup.py`

```python
from setuptools import setup, find_packages

setup(
    name="{{ cookiecutter.pkg_name }}",
    version="{{ cookiecutter.version }}",
    author="{{ cookiecutter.author_name }}",
    author_email="{{ cookiecutter.author_email }}",
    url="https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.repo_name }}",
    packages=find_packages(exclude=["tests*"]),
    python_requires=">={{ cookiecutter.python_version }}",
)

`pyproject.toml`

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "{{ cookiecutter.pkg_name }}"
version = "{{ cookiecutter.version }}"
authors = [
    {name = "{{ cookiecutter.author_name }}", email = "{{ cookiecutter.author_email }}"}
]
requires-python = ">={{ cookiecutter.python_version }}"

[tool.pytest.ini_options]
testpaths = ["tests"]

`init.py`

"""
{{ cookiecutter.project_name }} package.
"""

__version__ = "{{ cookiecutter.version }}"
__author__ = "{{ cookiecutter.author_name }}"

`tests/test_{{ cookiecutter.pkg_name }}.py`

import {{ cookiecutter.pkg_name }}


def test_version():
    assert {{ cookiecutter.pkg_name }}.__version__ == "{{ cookiecutter.version }}"

`.github/workflows/ci.yml`

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: "{{ cookiecutter.python_version }}"
      - run: pip install -e . pytest
      - run: pytest -v

`Dockerfile`

FROM python:{{ cookiecutter.python_version }}-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -e .
CMD ["python", "-m", "{{ cookiecutter.pkg_name }}"]

`LICENSE` (conditional with Jinja2)

{% if cookiecutter.license == "MIT" %}
MIT License

Copyright (c) {{ cookiecutter.author_name }}

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
{% elif cookiecutter.license == "proprietary" %}
Proprietary - {{ cookiecutter.author_name }}
All rights reserved.
{% endif %}

Step 4: Hooks

`hooks/pre_gen_project.py`

import re
import sys

SLUG_REGEX = r'^[_a-zA-Z][_a-zA-Z0-9]+$'
slug = '{{ cookiecutter.project_slug }}'

if not re.match(SLUG_REGEX, slug):
    print(f'ERROR: "{slug}" is not a valid project_slug.')
    sys.exit(1)

`hooks/post_gen_project.py`

import os
import shutil

if '{{ cookiecutter.use_docker }}' == 'no':
    if os.path.exists('Dockerfile'):
        os.remove('Dockerfile')

if '{{ cookiecutter.use_ci }}' == 'no':
    shutil.rmtree('.github', ignore_errors=True)

Step 5: `_copy_without_render`

# _copy_without_render
*.lock
package-lock.json

Step 6: Template README

Create a README.md at the template root (outside {{ }}) documenting:

What the template generates.
Available variables with defaults.
Usage examples.

Step 7: Test

# Generate with defaults
cookiecutter ./cookiecutter-python-package --output-dir /tmp/test

# Generate non-interactive
cookiecutter --no-input ./cookiecutter-python-package \
  project_name="My Awesome Package" \
  author_name="Jane Doe" \
  use_docker=yes \
  use_ci=github \
  --output-dir /tmp/test

# Verify
find /tmp/test -type f
cat /tmp/test/my_awesome_package/README.md

Step 8: Publish

git init
git add .
git commit -m "Initial template"
git tag v1.0.0
git remote add origin git@github.com:user/cookiecutter-python-package.git
git push -u origin main

Users can use it with:

cookiecutter https://github.com/user/cookiecutter-python-package.git

Summary

Define variables in cookiecutter.json with defaults and choices.
Derive secondary variables with Jinja2 in the JSON.
Use Jinja2 in file names and content.
Validate inputs with pre_gen_project.py.
Clean up conditional files with post_gen_project.py.
Document the template with a README.
Test before publishing.
Version with Git tags.