Skip to content
All posts

How to Create a Django Cookiecutter from Scratch

In this tutorial I will show you how you can create your own Django Cookiecutter, which you will be able to reuse or share with others.

A Django Cookiecutter is a project template: cookiecutter.json defines the questions, and a directory named {{ cookiecutter.project_slug }} holds the files to generate. Start with a small working Django project, replace its package name with that variable, then generate a separate project and run Django's checks inside it.

This walkthrough builds your own minimal template. It is not the larger Cookiecutter Django project, which offers many more deployment choices. If you only need a normal Django project, follow the basic Django setup instead.

Set up a disposable workspace

The commands below were checked with Python 3.11, Django 5.2.18 and Cookiecutter 2.6.0. These are a reproducible baseline, not a claim that they are the newest releases. The shell examples use macOS/Linux syntax; Windows virtual-environment activation differs.

Use a fresh directory outside any existing application. Create and activate a virtual environment, then install the two packages:

mkdir django-template-workspace
cd django-template-workspace
python -m venv .venv
source .venv/bin/activate
python -m pip install "Django==5.2.18" "cookiecutter==2.6.0"
mkdir bwd-django-cookiecutter
cd bwd-django-cookiecutter
django-admin startproject use_weird_name

These use Django's startproject command and Cookiecutter's template creation layout. The virtual environment stays outside the template, so it is not copied into generated projects.

Turn the project into a template

Open bwd-django-cookiecutter in your editor. Search the generated Python files for use_weird_name and replace that text with {{ cookiecutter.project_slug }}. This includes the settings-module references in manage.py, asgi.py and wsgi.py, plus the URL and WSGI settings in settings.py.

Rename both directories called use_weird_name to the literal name {{ cookiecutter.project_slug }}. Editor text replacement does not rename directories. The outer one contains manage.py; the inner one is the Python package.

Do not distribute the secret key generated by startproject. In the inner settings.py, add import os and replace the complete SECRET_KEY = ... line with:

import os

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]

Keep only one import os if your file already has it. This follows Django's environment-based secret-key guidance, using an application-specific environment-variable name. Each generated application must receive its own secret; this template intentionally has no fallback key. Do not commit real secrets to your template or generated repository.

At the template root, alongside the outer directory, create cookiecutter.json with exactly this content:

{
  "project_name": "My Awesome Project",
  "project_slug": "{{ cookiecutter.project_name.lower()|replace(' ', '_')|replace('-', '_')|replace('.', '_')|trim() }}"
}

cookiecutter.json is strict JSON: no /* comments */, // comments or trailing commas. Put explanations outside the file. The earlier version of this tutorial included comments in its JSON examples; those fail before Cookiecutter can generate a project.

The slug expression supplies a default, not a validator. Choose a Python package name such as my_awesome_project: no spaces, hyphens, leading digit or Python keyword such as class. You can override it when prompted. See Cookiecutter's input-variable documentation.

Your template now looks like this; the braces in the directory names are literal:

bwd-django-cookiecutter/
├── cookiecutter.json
└── {{ cookiecutter.project_slug }}/
    ├── manage.py
    └── {{ cookiecutter.project_slug }}/
        ├── __init__.py
        ├── asgi.py
        ├── settings.py
        ├── urls.py
        └── wsgi.py

Validate, generate, then enter the output

From bwd-django-cookiecutter, first check the JSON, then return to the workspace directory and generate a project:

python -m json.tool cookiecutter.json
cd ..
cookiecutter ./bwd-django-cookiecutter

This follows Cookiecutter's local-template usage. Accept the defaults for the first run. The new my_awesome_project directory appears beside bwd-django-cookiecutter, not inside the template's Python package. Never run manage.py inside a directory whose name still contains {{ ... }}.

Enter the generated project and provide a development key. In the same activated shell:

cd my_awesome_project
export DJANGO_SECRET_KEY="$(python -c 'from secrets import token_urlsafe; print(token_urlsafe(50))')"
python manage.py check
python manage.py migrate
python manage.py runserver

The key command uses Python's secrets module and keeps the generated value out of terminal output. Do not print or paste it into a commit. A new terminal needs the variable set again. For deployment, configure a persistent, unique secret through your hosting environment or secret manager; do not generate a different key on each server restart.

Check that port 8000 is available before starting the server. If another project uses it, leave that service alone and use a free port, for example python manage.py runserver 8001. Open the matching local URL. Django's development welcome page confirms that the generated settings and URL configuration load; it does not certify production readiness. Stop your server with Ctrl+C.

The migration and server commands are documented in Django's management-command reference. runserver is for development, not production. Before sharing the generated project, use the version-control guide to keep local databases, virtual environments and secret files out of Git.

Optionally add Poetry metadata

Get the minimal template working before adding more choices. For a Poetry 2 dependency-only project, add project_description to the context file:

{
  "project_name": "My Awesome Project",
  "project_slug": "{{ cookiecutter.project_name.lower()|replace(' ', '_')|replace('-', '_')|replace('.', '_')|trim() }}",
  "project_description": "A small Django project"
}

Then create this pyproject.toml inside the outer {{ cookiecutter.project_slug }} directory, beside manage.py:

[project]
name = "{{ cookiecutter.project_slug }}"
description = {{ cookiecutter.project_description | tojson }}
requires-python = ">=3.11,<4.0"
dependencies = ["Django==5.2.18"]

[tool.poetry]
package-mode = false

Jinja’s tojson filter quotes and escapes the description instead of inserting it into an already quoted string. This block was checked with Poetry 2.2.1 and ordinary descriptions containing quotes and backslashes. It uses Poetry's non-package mode; it does not build or publish a Python package.

Generate into a different output directory so you do not overwrite your first project. From the workspace directory, with the same virtual environment still active and Poetry 2 installed:

cookiecutter ./bwd-django-cookiecutter --output-dir generated-with-poetry
cd generated-with-poetry/my_awesome_project
poetry check
poetry install
poetry run python manage.py check

Keep DJANGO_SECRET_KEY set for the last command. Poetry resolves a separate environment when needed; the generated dependency declaration, not the template author's globally installed Django, controls that environment. Keep the generated poetry.lock with that project. For Poetry installation and environment setup, use the tested setup guide.

Troubleshooting and next steps

  • JSON decoding error: run python -m json.tool cookiecutter.json. Remove comments and trailing commas; renaming the file does not fix its syntax.
  • No manage.py in the current directory: enter the generated output, not the template root or inner Python package.
  • ModuleNotFoundError mentions the old name: check the settings-module strings and both renamed directories. Generate a fresh output after fixing the template; editing the template does not update an existing generated project.
  • KeyError: DJANGO_SECRET_KEY: set that variable in the shell or service running Django. Do not restore a shared hardcoded key to hide the error.
  • Output directory already exists: choose another --output-dir. Do not overwrite an application you have started editing.

Once the minimal version works, add one option at a time and generate a new project to test it. If you later add Django HTML templates, remember that Cookiecutter and Django both use template delimiters; read Cookiecutter's escaping guidance before copying them wholesale. A reusable template is useful only when its generated project works, not merely when its folder tree looks right.

More from Built with Django