The Django Template Engine
In this page:
What Is the Django Template Engine?
The template engine takes an HTML file containing special syntax and a Python dictionary of data (the context), and produces a final HTML string by substituting the placeholders with real values.
Note: Template files are just .html files stored inside a templates/ folder in your app.
Example: What Is the Django Template Engine?
{{ name }} and {{ unread_count }} are placeholders the engine replaces with real values from the view's context.
<!-- templates/greeting.html -->
<!DOCTYPE html>
<html>
<body>
<h1>Hello, {{ name }}!</h1>
<p>You have {{ unread_count }} new messages.</p>
</body>
</html>Two Kinds of Template Syntax
Double braces {{ variable }} output a value. Curly-brace-percent {% tag %} run template tags like loops, conditionals, and includes -- they don't output text directly.
Warning: Mixing up {{ }} and {% %} is the single most common Django template error for beginners.
Example: Two Kinds of Template Syntax
{{ username }} prints a value; {% if %}...{% endif %} controls whether the enclosed HTML renders at all.
<!-- output a variable -->
<p>{{ username }}</p>
<!-- run a tag (no output by itself) -->
{% if is_logged_in %}
<p>Welcome back!</p>
{% endif %}How Django Finds Your Templates
By default, Django looks for a templates/ folder inside each installed app. A template at myapp/templates/myapp/page.html is referenced in code as 'myapp/page.html'.
Note: Namespacing templates inside an app-named subfolder (templates/myapp/...) avoids name clashes between apps.
Warning: If TEMPLATES loaders can't find your file, Django raises TemplateDoesNotExist with the exact paths it searched.
Example: How Django Finds Your Templates
render() looks for myapp/page.html inside myapp/templates/ — the 'myapp/' prefix inside templates/ prevents name clashes when two different apps both have a page.html.
# myapp/views.py
from django.shortcuts import render
def show_page(request):
return render(request, 'myapp/page.html', {})The Template Engine in settings.py
The TEMPLATES setting configures which backend renders your templates and where it looks for them, including the APP_DIRS option that enables the per-app templates/ folder convention.
Example: The Template Engine in settings.py
APP_DIRS=True tells Django to automatically search every installed app's templates/ folder.
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.request',
],
},
},
]- Writing Python logic (loops, complex conditionals with multiple branches) directly in templates instead of preparing the data in the view first.
- Forgetting that template syntax uses double curly braces {{ }} for output but curly-brace-percent {% %} for tags, and mixing the two up.
- Putting .html template files outside the app's templates/ directory so Django's template loader can't find them.
- The Django Template Language (DTL) lets you embed variables and simple logic inside HTML using {{ }} and {% %} syntax.
- Templates are plain text files rendered by Django's template engine, which replaces placeholders with real context data.
- Keeping logic out of templates and in views/models keeps templates simple and readable.
Chapter Quiz — Complete all 10 topics to unlock
0/10 topics done
Complete these topics first: