Django Best Practices: Template Structure

There are two main ways to organize your template structure in Django: the default app-level way and a custom project-level approach.

Option 1: App Level

By default, the Django template loader will look for a templates folder within each app. But to avoid namespace issues, you also need to repeat the app name in a folder below that before adding your template file.

For example, if we had a Django project called django_project with a pages app and a home.html template file, the proper structure would be like this: within the pages app, we create a templates directory, then a pages directory, and finally our home.html file.

├── django_project
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
|   └── pages
|      ├── __init__.py
│      ├── admin.py
│      ├── apps.py
│      ├── models.py
│      ├── tests.py
│      └── views.py
|      ├── templates
|          ├── pages
|              ├── home.html
└── manage.py

This approach is demonstrated in the official Django polls tutorial and works just fine.

Option 2: Project Level

As Django projects grow, having all the templates in one place is often more convenient than hunting for them within multiple apps. We can do this with a single-line change to our settings.py file.

Update the 'DIRS' config under TEMPLATES as follows, which specifies that , in addition, to looking for an app-level templates directory, the Django template loader should also look for a project-level templates directory.

# settings.py
TEMPLATES = [
    {
        ...
        "DIRS": [BASE_DIR / "templates"],
        ...
    },
]

Then, create a templates directory at the same level as the project. Here's an example of what it would look like with the home.html file.

├── django_project
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
|   └── pages
|      ├── __init__.py
│      ├── admin.py
│      ├── apps.py
│      ├── models.py
│      ├── tests.py
│      └── views.py
├── templates
    ├── home.html
└── manage.py

Next Steps

Remember, if you have overridden DIRS in the settings.py file, the Django template loader will first look there and then look to APP_DIRS for an app-level templates directory. There is no "right" way to organize templates within your Django project, but many developers, myself included, prefer the project-level approach.