Alanso Mathew

Posted on May 12

Django Templates: Rendering, Context, and Performance Tips — A Complete Production Guide

#django #python #fullstack #restapi

From render() to custom template tags, the cached loader, context processors, and fragment caching — a engineer's complete guide to Django's template system.

Orginally Posted : https://alansomathewdev.blogspot.com/2026/05/django-templates-rendering-context-and.html

Introduction
Why This Matters in Production Systems
Core Concepts
Architecture Design
Step-by-Step Implementation
Code Examples
Performance Optimization
Security Best Practices
Common Developer Mistakes
Real Production Use Cases
Conclusion

Introduction

Django's template system occupies a deceptively large share of what happens between a database query and a browser rendering HTML. Most Django tutorials treat templates as passive HTML files with a few {{ variable }} placeholders sprinkled in. That mental model works for small projects. It breaks at scale.

In a production system serving thousands of requests per minute, templates are a critical performance surface. A poorly structured template hierarchy causes repeated file system lookups. An uncached template loader recompiles templates on every single request. An over-stuffed context dict passes megabytes of Python objects to a rendering engine. Context processors running synchronous database queries add 15–50ms to every render cycle. An unsafe use of autoescape=False opens cross-site scripting vulnerabilities that bypass all your other security controls.

This guide is the one that covers all of it. We'll trace a template from raw HTML file to rendered string, dissect the Context and RequestContext objects, build custom template tags and filters, architect a production template structure with proper inheritance, configure the cached loader, implement fragment caching, and cover the security and deployment considerations that experienced Django engineers think about but rarely write down.

Whether you're rendering a homepage, building a complex admin dashboard, or running a high-traffic content platform, the patterns here will help you do it correctly, efficiently, and safely.

Why This Matters in Production Systems

Template rendering happens on every server-rendered HTTP response. On a content-heavy application, it can account for 20–40% of total response time. Here's where the cost accumulates:

Template compilation. Django must parse and compile every template the first time it's used. The system only parses raw template code once — when you create the Template object. After that, it's stored as a tree structure for performance. Without the cached loader, that compilation happens on every request. With it, it happens once at startup.

Context processor overhead. Every context processor in context_processors runs on every RequestContext. Each active processor can add 15–50ms to every template render cycle. Processors that make database calls — however fast — multiply their cost by your request throughput.

N+1 in templates. The most common template performance bug: a template accesses a related object in a {% for %} loop that wasn't prefetched. Each iteration triggers a new database query. This is invisible from the view — the QuerySet appears complete — but the template evaluation triggers lazy loading.

Template inheritance depth. Deep inheritance chains ({% extends %} stacking 6–7 levels deep) force Django to load and parse multiple template files per render. This adds file I/O and parsing overhead proportional to inheritance depth.

Unsafe context data. Passing entire ORM objects with dozens of fields to templates when only two are needed wastes serialisation time and memory.

Understanding the template system deeply is how you avoid all of these — and how you optimise when you encounter them in production.

Core Concepts

The Three-Step Template Process

Using the template system is a three-step process: configure an engine, compile template code into a Template, and render the template with a Context. Most Django code uses the high-level render() shortcut, but understanding the lower-level steps is essential for debugging and optimisation.

from django.template import Engine, Context

# Low-level: compile then render
engine   = Engine.get_default()
template = engine.get_template("catalog/product_detail.html")
html     = template.render(Context({"product": product}))

# High-level shortcut (what you use in views)
from django.shortcuts import render
return render(request, "catalog/product_detail.html", {"product": product})

`Context` vs `RequestContext`

Django provides two context classes, and the distinction matters:

Context is a plain dict-like object. It maps variable names to values. It does not know about the HTTP request. It does not run context processors.

RequestContext is a Context subclass that takes an HttpRequest and runs all configured context processors from TEMPLATES[0]['OPTIONS']['context_processors']. This is what render() creates automatically.

from django.template import RequestContext, Context

# RequestContext: runs context processors (what render() uses)
ctx = RequestContext(request, {"product": product})
# Adds: request, user, csrf_token, messages, etc.

# Context: bare dict, no processors, no request awareness
ctx = Context({"product": product})
# Useful for: rendering templates outside the request cycle
# (management commands, Celery tasks, email generation)

Template Variables, Tags, Filters, and Comments

Django's template language has four constructs:

{{ variable }}              ← Variable output
{% tag %}...{% endtag %}    ← Template logic (loops, conditions, includes)
{{ variable|filter }}       ← Transform variable output
{# comment #}              ← Single-line comment (not rendered)

Variable resolution uses dot notation to navigate dicts, objects, and lists:

{{ product.name }}          {# attribute access #}
{{ product.get_status_display }} {# method call — called with no args #}
{{ request.user.email }}    {# chained attribute access #}
{{ items.0 }}               {# list index access #}
{{ metadata.price }}        {# dict key access #}

The Template Loader System

Django's template loader is responsible for finding template files. It works through a list of loaders configured in TEMPLATES:

Loader	What It Does
`filesystem.Loader`	Searches directories listed in `DIRS`
`app_directories.Loader`	Searches `templates/` in every installed app
`cached.Loader`	Wraps other loaders; caches compiled templates in memory
`locmem.Loader`	Loads from an in-memory dict (testing only)

Context Processors

Context processors are callables that accept an HttpRequest and return a dict merged into every RequestContext. They're the mechanism that makes {{ user }}, {{ request }}, and {% csrf_token %} available without explicitly passing them from every view:

# Built-in context processors (default settings)
TEMPLATES = [{
    "BACKEND": "django.template.backends.django.DjangoTemplates",
    "OPTIONS": {
        "context_processors": [
            "django.template.context_processors.debug",
            "django.template.context_processors.request",  # → request
            "django.contrib.auth.context_processors.auth",  # → user, perms
            "django.contrib.messages.context_processors.messages",  # → messages
        ],
    },
}]

Architecture Design

The Template Rendering Pipeline

view calls render(request, "catalog/product_detail.html", context)
                        │
                        ▼
        ┌──────────────────────────────────────────┐
        │     Django Template Backend               │
        │     (DjangoTemplates)                     │
        └──────────────┬───────────────────────────┘
                       │
                       ▼
        ┌──────────────────────────────────────────┐
        │         Template Loader Chain             │
        │                                           │
        │  cached.Loader (wraps all below)          │
        │    ↓ cache MISS → find template file      │
        │  filesystem.Loader → checks DIRS          │
        │  app_directories.Loader → checks apps/    │
        │    ↓ file found                           │
        │  Template.compile() → Node tree           │
        │    ↓ stored in cache                      │
        │  cache HIT → return cached Node tree      │
        └──────────────┬───────────────────────────┘
                       │ compiled Template object
                       ▼
        ┌──────────────────────────────────────────┐
        │         RequestContext                    │
        │                                           │
        │  base context dict (from view)            │
        │  + context processor outputs:             │
        │    → {"request": HttpRequest, ...}        │
        │    → {"user": User, "perms": ...}         │
        │    → {"messages": [...]}                  │
        │    → {"DEBUG": True/False}                │
        └──────────────┬───────────────────────────┘
                       │ context ready
                       ▼
        ┌──────────────────────────────────────────┐
        │         Template.render(context)          │
        │                                           │
        │  Walk the compiled Node tree              │
        │  Resolve variables against context        │
        │  Execute tags ({% for %}, {% if %}, etc.) │
        │  Apply filters (|date, |truncatewords)    │
        │  Autoescape all output (default: True)    │
        └──────────────┬───────────────────────────┘
                       │ rendered HTML string
                       ▼
                 HttpResponse(html)

Production Template Directory Structure

myproject/
│
├── templates/                   ← Project-level templates (global)
│   ├── base.html                ← Site-wide base layout
│   ├── base_email.html          ← Email base template
│   ├── errors/
│   │   ├── 400.html
│   │   ├── 403.html
│   │   ├── 404.html
│   │   └── 500.html
│   └── includes/                ← Shared partials
│       ├── _navbar.html
│       ├── _footer.html
│       ├── _pagination.html
│       └── _messages.html
│
├── apps/
│   ├── catalog/
│   │   └── templates/
│   │       └── catalog/         ← Namespaced: "catalog/product_detail.html"
│   │           ├── product_list.html
│   │           ├── product_detail.html
│   │           └── includes/
│   │               ├── _product_card.html
│   │               └── _product_filters.html
│   │
│   ├── orders/
│   │   └── templates/
│   │       └── orders/
│   │           ├── order_list.html
│   │           ├── order_detail.html
│   │           └── order_confirm_delete.html
│   │
│   └── users/
│       └── templates/
│           └── users/
│               ├── profile.html
│               └── account_settings.html
│
└── config/
    └── settings/
        └── base.py              ← TEMPLATES configuration

Step-by-Step Implementation

Step 1: Configure the Template Engine

# config/settings/base.py
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent.parent

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",

        # Project-level template directories (searched before app directories)
        "DIRS": [BASE_DIR / "templates"],

        # Also search each app's templates/ subdirectory
        "APP_DIRS": False,  # ← False because we specify loaders manually below

        "OPTIONS": {
            "loaders": [
                # In production: cached.Loader wraps all loaders
                # Template compilation happens once; subsequent renders use cache
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                    ],
                ),
            ],
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
                # Custom project-wide context processor
                "apps.core.context_processors.site_settings",
            ],
            "builtins": [
                # Auto-load these tag libraries without {% load %} in every template
                "django.contrib.humanize.templatetags.humanize",
                "apps.core.templatetags.core_tags",
            ],
        },
    }
]

# config/settings/development.py
# In development: disable cached.Loader so template changes take effect immediately
TEMPLATES[0]["OPTIONS"]["loaders"] = [
    "django.template.loaders.filesystem.Loader",
    "django.template.loaders.app_directories.Loader",
]

Step 2: Build the Template Hierarchy

{# templates/base.html — the root layout #}
<!DOCTYPE html>
<html lang="{% block lang %}en{% endblock %}" data-theme="{% block theme %}light{% endblock %}">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{% block title %}{{ site_name }}{% endblock %}</title>
    <meta name="description" content="{% block meta_description %}{% endblock %}" />

    {% block extra_css %}{% endblock %}
</head>
<body>
    {% include "includes/_navbar.html" %}

    {# Messages — available via context processor #}
    {% include "includes/_messages.html" %}

    <main id="main-content">
        {% block content %}{% endblock %}
    </main>

    {% include "includes/_footer.html" %}

    {% block extra_js %}{% endblock %}
</body>
</html>

{# apps/catalog/templates/catalog/product_detail.html #}
{% extends "base.html" %}
{% load humanize %}

{% block title %}{{ product.name }} | {{ block.super }}{% endblock %}

{% block meta_description %}{{ product.description|truncatewords:25 }}{% endblock %}

{% block content %}
<article class="product-detail">
    <h1>{{ product.name }}</h1>

    <div class="product-price">
        {% if product.on_sale %}
            <span class="original-price">{{ product.price|intcomma }}</span>
            <span class="sale-price">{{ product.sale_price|intcomma }}</span>
        {% else %}
            <span>{{ product.price|intcomma }}</span>
        {% endif %}
    </div>

    <p class="product-stock">
        {% if product.stock > 10 %}
            In stock
        {% elif product.stock > 0 %}
            Only {{ product.stock }} left
        {% else %}
            Out of stock
        {% endif %}
    </p>

    {% if product.tags.all %}
        <div class="tags">
            {% for tag in product.tags.all %}
                <a href="{% url 'catalog:tag' slug=tag.slug %}" class="tag">
                    {{ tag.name }}
                </a>
            {% endfor %}
        </div>
    {% endif %}

    {% include "catalog/includes/_product_related.html" with products=related_products %}
</article>
{% endblock %}

Step 3: Build Context Processors

# apps/core/context_processors.py
from django.conf import settings


def site_settings(request):
    """
    Injects global site configuration into every template context.
    Data here is static — loaded once at startup, not per-request.
    Keep this function fast: no database calls, no network I/O.
    """
    return {
        "site_name":    settings.SITE_NAME,
        "site_url":     settings.SITE_URL,
        "contact_email": settings.CONTACT_EMAIL,
        "ENVIRONMENT":  settings.ENVIRONMENT,
        "ANALYTICS_ID": getattr(settings, "ANALYTICS_ID", ""),
    }


def cart_summary(request):
    """
    Injects the cart item count into every template context.
    Uses request-scoped caching to avoid hitting the DB on every render.

    IMPORTANT: Cache the result on the request object.
    This processor runs on EVERY RequestContext — not just cart pages.
    """
    if not request.user.is_authenticated:
        return {"cart_count": 0}

    # Cache on the request object to avoid repeated DB hits within the same request
    if not hasattr(request, "_cart_count"):
        from apps.cart.selectors import get_cart_item_count
        request._cart_count = get_cart_item_count(user=request.user)

    return {"cart_count": request._cart_count}

Code Examples

Custom Template Tags

Template tags are where you extend Django's template language with project-specific presentation logic. Keep them focused on presentation — not business logic:

# apps/core/templatetags/core_tags.py
from django import template
from django.utils.html import format_html
from django.utils.safestring import mark_safe

register = template.Library()


# ── SIMPLE TAGS ─────────────────────────────────────────────────────

@register.simple_tag(takes_context=True)
def active_link(context, url_name, css_class="active"):
    """
    Returns the active CSS class if the current URL matches url_name.
    Usage: <a href="..." class="{% active_link 'catalog:list' %}">Products</a>
    """
    request = context.get("request")
    if request is None:
        return ""

    from django.urls import reverse, NoReverseMatch
    try:
        url = reverse(url_name)
        if request.path.startswith(url):
            return css_class
    except NoReverseMatch:
        pass
    return ""


@register.simple_tag
def settings_value(name: str):
    """
    Exposes specific settings values to templates.
    Only whitelist safe, non-sensitive settings.

    Usage: {% settings_value "SITE_NAME" %}
    """
    from django.conf import settings

    ALLOWED = {"SITE_NAME", "ENVIRONMENT", "CONTACT_EMAIL", "SUPPORT_URL"}
    if name not in ALLOWED:
        return ""
    return getattr(settings, name, "")


# ── INCLUSION TAGS ───────────────────────────────────────────────────

@register.inclusion_tag("includes/_pagination.html", takes_context=True)
def pagination(context, page_obj, url_param="page"):
    """
    Renders the pagination component.
    Usage: {% pagination page_obj %}
    """
    return {
        "request":   context.get("request"),
        "page_obj":  page_obj,
        "url_param": url_param,
    }


@register.inclusion_tag("catalog/includes/_product_card.html")
def product_card(product, show_price=True, show_badge=False):
    """
    Renders a reusable product card.
    Usage: {% product_card product show_price=True %}
    """
    return {
        "product":    product,
        "show_price": show_price,
        "show_badge": show_badge,
    }


# ── FILTERS ─────────────────────────────────────────────────────────

@register.filter(name="currency")
def currency_format(value, currency_code="USD"):
    """
    Formats a Decimal as a currency string.
    Usage: {{ product.price|currency }}
           {{ price|currency:"EUR" }}
    """
    try:
        amount = float(value)
    except (TypeError, ValueError):
        return value

    symbols = {"USD": "$", "EUR": "€", "GBP": "£"}
    symbol = symbols.get(currency_code, currency_code)
    return f"{symbol}{amount:,.2f}"


@register.filter
def multiply(value, arg):
    """
    Multiplies value by arg.
    Usage: {{ item.quantity|multiply:item.unit_price }}
    """
    try:
        return float(value) * float(arg)
    except (TypeError, ValueError):
        return 0


@register.filter
def status_badge(status_value):
    """
    Returns an HTML badge for a status string.
    Autoescaped output is explicitly marked safe here.
    Usage: {{ order.status|status_badge }}
    """
    STATUS_STYLES = {
        "pending":    ("warning", "Pending"),
        "processing": ("info",    "Processing"),
        "shipped":    ("primary", "Shipped"),
        "delivered":  ("success", "Delivered"),
        "cancelled":  ("danger",  "Cancelled"),
    }
    style, label = STATUS_STYLES.get(status_value, ("secondary", status_value))
    return format_html(
        '<span class="badge badge-{}">{}</span>',
        style, label
    )

Custom Template Tag with Complex Logic

For tags that need to do more — run queries, compute values, inject results — use the full Node pattern:

# apps/notifications/templatetags/notification_tags.py
from django import template
from django.core.cache import cache

register = template.Library()


class UnreadNotificationsNode(template.Node):
    """
    Template Node for {% get_unread_notifications as varname %}.
    Queries the notifications count, caches per-user for 60 seconds.
    """
    def __init__(self, var_name: str):
        self.var_name = var_name

    def render(self, context):
        request = context.get("request")
        if request is None or not request.user.is_authenticated:
            context[self.var_name] = 0
            return ""

        cache_key = f"notif_count:{request.user.id}"
        count = cache.get(cache_key)

        if count is None:
            from apps.notifications.selectors import get_unread_count
            count = get_unread_count(user=request.user)
            cache.set(cache_key, count, timeout=60)

        context[self.var_name] = count
        return ""   # Node.render() must return a string, even if empty


@register.tag("get_unread_notifications")
def get_unread_notifications(parser, token):
    """
    Usage: {% get_unread_notifications as unread_count %}
    Then:  {{ unread_count }}
    """
    try:
        tag_name, _, var_name = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError(
            f"{token.contents.split()[0]} requires: as <var_name>"
        )
    return UnreadNotificationsNode(var_name)

{# templates/includes/_navbar.html #}
{% load notification_tags %}
{% get_unread_notifications as unread_count %}

<nav>
    ...
    {% if unread_count %}
        <span class="badge">{{ unread_count }}</span>
    {% endif %}
</nav>

Context in Views: Best Practices

# apps/catalog/views.py
from django.shortcuts import render, get_object_or_404
from django.contrib.auth.decorators import login_required
from apps.catalog.models import Product
from apps.catalog.selectors import get_related_products


def product_detail(request, slug: str):
    """
    Build a lean context dict — only pass what the template actually uses.

    BAD:  context = {"product": product}  # ORM object with all 20+ fields
    GOOD: Prefetch relationships so the template doesn't trigger N+1 queries
    BEST: Use values() for list views; pass full objects only for detail views
    """
    product = get_object_or_404(
        Product.objects
        .select_related("category", "brand")
        .prefetch_related("tags", "images"),
        slug=slug,
        status=Product.Status.ACTIVE,
    )

    return render(request, "catalog/product_detail.html", {
        "product":          product,
        "related_products": get_related_products(product, limit=4),
        "breadcrumbs": [
            {"label": "Home",     "url": "/"},
            {"label": product.category.name, "url": product.category.get_absolute_url()},
            {"label": product.name, "url": None},  # current page — no link
        ],
    })


def product_list(request):
    """
    For list views: use values() to avoid loading full ORM objects.
    The template only needs id, name, slug, price — not all 20 fields.
    """
    products = (
        Product.objects
        .filter(status=Product.Status.ACTIVE)
        .select_related("category")
        .only("id", "name", "slug", "price", "thumbnail", "stock", "category__name")
        .order_by("-created_at")
    )

    return render(request, "catalog/product_list.html", {
        "products": products,
        "total_count": products.count(),
    })

Generating Emails with Templates

# apps/notifications/services.py
from django.core.mail import EmailMultiAlternatives
from django.template.loader import render_to_string
from django.utils.html import strip_tags


def send_order_confirmation_email(order) -> None:
    """
    Renders both HTML and plain-text email from templates.
    Uses Context (not RequestContext) — no HTTP request available here.
    """
    context = {
        "order":      order,
        "user":       order.user,
        "items":      order.items.select_related("product"),
        "support_url": "https://myapp.com/support/",
    }

    # Render HTML version
    html_body = render_to_string(
        "emails/order_confirmation.html",
        context,
        request=None,  # ← explicitly None for non-request contexts
    )

    # Plain text: strip HTML tags from the rendered HTML
    text_body = strip_tags(html_body)

    email = EmailMultiAlternatives(
        subject=f"Order Confirmed — #{order.id}",
        body=text_body,
        from_email="orders@myapp.com",
        to=[order.user.email],
    )
    email.attach_alternative(html_body, "text/html")
    email.send()

Testing Template Contexts

# apps/catalog/tests/test_views.py
from django.test import TestCase, RequestFactory
from django.urls import reverse
from apps.catalog.tests.factories import ProductFactory


class ProductDetailViewTests(TestCase):

    def setUp(self):
        self.product = ProductFactory(status="active")

    def test_context_contains_product(self):
        response = self.client.get(
            reverse("catalog:product-detail", kwargs={"slug": self.product.slug})
        )
        self.assertEqual(response.status_code, 200)
        self.assertEqual(response.context["product"], self.product)

    def test_related_products_in_context(self):
        response = self.client.get(
            reverse("catalog:product-detail", kwargs={"slug": self.product.slug})
        )
        self.assertIn("related_products", response.context)
        self.assertLessEqual(len(response.context["related_products"]), 4)

    def test_template_used(self):
        response = self.client.get(
            reverse("catalog:product-detail", kwargs={"slug": self.product.slug})
        )
        self.assertTemplateUsed(response, "catalog/product_detail.html")
        self.assertTemplateUsed(response, "base.html")  # inheritance chain

    def test_product_price_rendered(self):
        response = self.client.get(
            reverse("catalog:product-detail", kwargs={"slug": self.product.slug})
        )
        self.assertContains(response, str(self.product.price))

    def test_out_of_stock_message(self):
        out_of_stock = ProductFactory(status="active", stock=0)
        response = self.client.get(
            reverse("catalog:product-detail", kwargs={"slug": out_of_stock.slug})
        )
        self.assertContains(response, "Out of stock")

Performance Optimization

1. Enable the Cached Template Loader in Production

This is the single most impactful template performance change. Enabling the cached template loader often improves performance drastically, as it avoids compiling each template every time it needs to be rendered.

# config/settings/production.py
TEMPLATES[0]["OPTIONS"]["loaders"] = [
    (
        "django.template.loaders.cached.Loader",
        [
            "django.template.loaders.filesystem.Loader",
            "django.template.loaders.app_directories.Loader",
        ],
    )
]

Benchmarks show a 40% reduction in template lookup times for applications with 500+ template files when using the cached loader.

Critical: Disable the cached loader in development. Template changes won't be reflected without a server restart if it's enabled:

# config/settings/development.py
TEMPLATES[0]["OPTIONS"]["loaders"] = [
    "django.template.loaders.filesystem.Loader",
    "django.template.loaders.app_directories.Loader",
]

2. Fragment Caching: Cache Expensive Template Sections

{# Cache the product listing card — it changes rarely #}
{% load cache %}

{% cache 900 product_card product.id %}
    {# This entire block is cached for 900 seconds (15 min) per product #}
    {% include "catalog/includes/_product_card.html" %}
{% endcache %}

{# Cache with user-specific key — different cache per user #}
{% cache 300 user_dashboard request.user.id %}
    <div class="dashboard-summary">
        {# Expensive dashboard data #}
    </div>
{% endcache %}

# Programmatic fragment caching in views
from django.core.cache import cache
from django.template.loader import render_to_string


def get_product_card_html(product_id: int) -> str:
    """
    Cache the rendered HTML of a product card.
    Invalidate by deleting the cache key when the product changes.
    """
    cache_key = f"product_card_html:{product_id}"
    html = cache.get(cache_key)

    if html is None:
        from apps.catalog.models import Product
        product = Product.objects.select_related("category").get(pk=product_id)
        html = render_to_string("catalog/includes/_product_card.html", {"product": product})
        cache.set(cache_key, html, timeout=900)

    return html

3. Use `{% include %}` Correctly — Avoid Database Hits in Includes

{% include %} renders a template fragment in the current context. It shares the parent context automatically, so don't pass redundant variables:

{# BAD — passing the entire context redundantly #}
{% include "includes/_product_card.html" with product=product category=product.category tags=product.tags.all %}

{# GOOD — include shares parent context; only pass what differs #}
{% include "includes/_product_card.html" %}

{# GOOD — use "with" for override only, "only" to isolate #}
{% include "includes/_mini_card.html" with product=product only %}
{# "only" prevents leaking parent context into the include — good for reusable components #}

4. Avoid Logic in Templates — Compute in Views

Complex logic in templates is slow and hard to test. Do the computation in the view and pass ready-to-render data:

# BAD — complex conditional logic repeated in template
# Template: {% if order.total > 100 and order.user.subscription.plan == "pro" and not order.has_discount %}

# GOOD — compute in view, pass a simple boolean
def order_detail(request, pk):
    order = get_object_or_404(Order, pk=pk, user=request.user)
    return render(request, "orders/detail.html", {
        "order":               order,
        "show_upgrade_banner": (
            order.total > 100
            and request.user.subscription.plan != "pro"
            and not order.has_discount
        ),
    })

# Template: {% if show_upgrade_banner %}

5. Trim Unused Context Processors

Each active context processor adds overhead — 15–50ms per render cycle. Audit and remove unused processors:

# config/settings/production.py
TEMPLATES[0]["OPTIONS"]["context_processors"] = [
    # "django.template.context_processors.debug",  ← REMOVE in production
    "django.template.context_processors.request",
    "django.contrib.auth.context_processors.auth",
    "django.contrib.messages.context_processors.messages",
    "apps.core.context_processors.site_settings",
    # Remove if you're not using cart globally:
    # "apps.cart.context_processors.cart_summary",
]

Security Best Practices

1. Autoescaping: The Default That Protects You

Django's template engine auto-escapes all variable output by default. This prevents cross-site scripting (XSS) by converting dangerous characters before rendering:

Character   →  Escaped HTML Entity
<           →  &lt;
>           →  &gt;
'           →  &#x27;
"           →  &quot;
&           →  &amp;

{# This is safe — Django escapes any HTML in user_bio #}
<p>{{ user.bio }}</p>

{# DANGEROUS — disabling autoescape allows XSS #}
{% autoescape off %}
    {{ user.bio }}   {# if bio contains <script>alert('XSS')</script> — you're done #}
{% endautoescape %}

Only disable autoescape when you've explicitly sanitised the content and know it's safe (e.g., a field that stores pre-sanitised HTML from a trusted rich-text editor).

2. Using `mark_safe` and `format_html` Correctly

When your custom template tag or filter generates HTML, you must mark it as safe — but only after ensuring it's sanitised:

from django.utils.html import format_html, mark_safe, escape

# DANGEROUS — marking user input as safe allows XSS
def bad_tag(user_input):
    html = f"<span>{user_input}</span>"
    return mark_safe(html)   # ← user_input is never escaped!

# SAFE — format_html escapes all arguments before inserting
def good_tag(user_input, css_class):
    return format_html(
        '<span class="{}">{}</span>',
        css_class,   # ← escaped
        user_input,  # ← escaped
    )

# SAFE — escape explicitly when building complex strings
def good_complex_tag(items):
    html_parts = [format_html("<li>{}</li>", item) for item in items]
    return mark_safe("".join(html_parts))  # ← each part already escaped

3. Protect CSRF in All Forms

The {% csrf_token %} tag is required in every HTML form that submits via POST, PUT, or DELETE:

{# Every form needs this — CsrfViewMiddleware will reject the request without it #}
<form method="POST" action="{% url 'orders:create' %}">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Place Order</button>
</form>

For AJAX forms, include the CSRF token in the request headers using JavaScript:

// Read CSRF token from the cookie
function getCsrfToken() {
    return document.cookie
        .split('; ')
        .find(row => row.startsWith('csrftoken='))
        ?.split('=')[1];
}

// Include in every AJAX POST
fetch('/api/orders/', {
    method: 'POST',
    headers: {
        'X-CSRFToken': getCsrfToken(),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(data),
});

4. Never Render User-Controlled Template Strings

A critical vulnerability specific to template systems: never pass user-provided content as a template string:

# CATASTROPHICALLY DANGEROUS — Server Side Template Injection (SSTI)
# Attacker submits: {{ request.user.password }}
# Or worse: {% debug %}
user_template_string = request.POST.get("custom_message")
template = Template(user_template_string)       # ← NEVER DO THIS
html = template.render(Context({"user": request.user}))

# SAFE — render user content as data, never as template code
user_message = request.POST.get("custom_message")
return render(request, "notifications/message.html", {
    "user_message": user_message,  # ← autoescaped as data
})

5. Content Security Policy (CSP) Headers

Configure CSP headers to prevent XSS even if your autoescaping is bypassed:

# Using django-csp or middleware-level headers
# config/settings/production.py
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "csp.middleware.CSPMiddleware",  # django-csp
    ...
]

CSP_DEFAULT_SRC = ("'self'",)
CSP_SCRIPT_SRC  = ("'self'", "https://cdn.myapp.com")
CSP_STYLE_SRC   = ("'self'", "https://fonts.googleapis.com")
CSP_IMG_SRC     = ("'self'", "data:", "https://cdn.myapp.com")
CSP_FONT_SRC    = ("'self'", "https://fonts.gstatic.com")

Common Developer Mistakes

❌ Mistake 1: Triggering N+1 Queries in Template Loops

{# BAD — order.user is a ForeignKey; accesses the DB on every iteration #}
{% for order in orders %}
    <td>{{ order.user.email }}</td>      {# ← DB query per order #}
    {% for item in order.items.all %}    {# ← DB query per order #}
        <td>{{ item.product.name }}</td> {# ← DB query per item #}
    {% endfor %}
{% endfor %}

# FIX — prefetch everything the template touches before rendering
orders = (
    Order.objects
    .filter(user=request.user)
    .select_related("user")
    .prefetch_related("items__product")
)

❌ Mistake 2: Putting Business Logic in Templates

{# BAD — complex calculations in the template #}
{% for item in order.items.all %}
    {# This calculates subtotal in template — no caching, no testing #}
    <td>{{ item.quantity|multiply:item.unit_price }}</td>
{% endfor %}
<td>{{ order.total|add:order.tax|add:order.shipping }}</td>

{# GOOD — compute in the view or model, pass ready values #}
{{ item.subtotal }}
{{ order.grand_total }}

❌ Mistake 3: Using `APP_DIRS: True` and Manual Loaders Simultaneously

# BAD — this raises ImproperlyConfigured
TEMPLATES = [{
    "APP_DIRS": True,         # ← sets app_directories.Loader automatically
    "OPTIONS": {
        "loaders": [...]      # ← can't specify loaders when APP_DIRS is True!
    },
}]

# GOOD — use one or the other
# Option A: APP_DIRS=True (simple, no cached loader)
TEMPLATES = [{"APP_DIRS": True, "OPTIONS": {...}}]

# Option B: APP_DIRS=False, specify loaders manually (allows cached.Loader)
TEMPLATES = [{"APP_DIRS": False, "OPTIONS": {"loaders": [...]}}]

❌ Mistake 4: Database Queries in Context Processors

# BAD — DB query runs on EVERY template render across the entire site
def bad_processor(request):
    return {
        "categories": Category.objects.filter(is_active=True),  # ← every request!
    }

# GOOD — cache the result
def good_processor(request):
    from django.core.cache import cache
    categories = cache.get("active_categories")
    if categories is None:
        categories = list(Category.objects.filter(is_active=True).values("id", "name", "slug"))
        cache.set("active_categories", categories, timeout=3600)
    return {"categories": categories}

❌ Mistake 5: Using `{% load %}` in Every Template Instead of `builtins`

{# BAD — repeating {% load %} in every template that uses these tags #}
{% extends "base.html" %}
{% load humanize %}
{% load core_tags %}
{% load i18n %}

# GOOD — add frequently used tag libraries to builtins
TEMPLATES[0]["OPTIONS"]["builtins"] = [
    "django.contrib.humanize.templatetags.humanize",
    "django.templatetags.i18n",
    "apps.core.templatetags.core_tags",
]
# Now they're available in every template without {% load %}

Real Production Use Cases

Use Case 1: E-Commerce — Cached Product Cards at Scale

A content-heavy product listing page with 48 products per page. Each product card renders the product name, price, thumbnail, category, and tags:

# apps/catalog/views.py
from django.core.cache import cache
from django.template.loader import render_to_string
from django.http import HttpResponse
from django.template import RequestContext


def product_list(request):
    """
    Renders a product listing page with fragment-cached cards.
    Each card is cached individually for 15 minutes.
    Cache is invalidated when the product model is saved (via signals).
    """
    products = (
        Product.objects
        .active()
        .select_related("category")
        .prefetch_related("tags")
        .only("id", "name", "slug", "price", "thumbnail", "stock")
        .order_by("-created_at")
    )

    # Pre-render each card; serve from cache if available
    rendered_cards = []
    for product in products:
        cache_key = f"product_card:{product.id}:v3"
        html = cache.get(cache_key)
        if html is None:
            html = render_to_string(
                "catalog/includes/_product_card.html",
                {"product": product},
                request=request,
            )
            cache.set(cache_key, html, timeout=900)
        rendered_cards.append(html)

    return render(request, "catalog/product_list.html", {
        "rendered_cards": rendered_cards,
        "total": len(rendered_cards),
    })

{# catalog/product_list.html #}
{% extends "base.html" %}
{% block content %}
<div class="product-grid">
    {% for card_html in rendered_cards %}
        {{ card_html }}   {# Pre-rendered, no further template processing #}
    {% endfor %}
</div>
{% endblock %}

Use Case 2: Transactional Email Rendering

# apps/notifications/email_service.py
from django.template.loader import render_to_string
from django.utils.html import strip_tags
from django.core.mail import EmailMultiAlternatives


NOTIFICATION_TEMPLATES = {
    "order_confirmed":    "emails/order_confirmed.html",
    "password_reset":     "emails/password_reset.html",
    "subscription_expiry": "emails/subscription_expiry.html",
    "team_invitation":    "emails/team_invitation.html",
}

NOTIFICATION_SUBJECTS = {
    "order_confirmed":    "Your Order #{order_id} Is Confirmed",
    "password_reset":     "Reset Your Password",
    "subscription_expiry": "Your Subscription Expires in {days} Days",
    "team_invitation":    "{inviter} Invited You to Join {team}",
}


def send_notification_email(notification_type: str, recipient_email: str, context: dict) -> None:
    """
    Centralized email rendering service.
    All emails go through one function, ensuring consistent structure.
    """
    template_name = NOTIFICATION_TEMPLATES.get(notification_type)
    if not template_name:
        raise ValueError(f"Unknown notification type: {notification_type}")

    subject_template = NOTIFICATION_SUBJECTS[notification_type]
    subject = subject_template.format(**context)

    html_body = render_to_string(template_name, context)
    text_body = strip_tags(html_body)

    email = EmailMultiAlternatives(
        subject=subject,
        body=text_body,
        from_email="no-reply@myapp.com",
        to=[recipient_email],
    )
    email.attach_alternative(html_body, "text/html")
    email.send(fail_silently=False)

Use Case 3: Admin Dashboard with Jinja2 for Performance

For compute-heavy internal dashboards where the Django template language's limitations become apparent, Jinja2 can be configured as an alternative backend:

# config/settings/base.py — configure both backends
TEMPLATES = [
    {
        # Primary: Django Template Language for all public templates
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": False,
        "OPTIONS": {
            "loaders": [
                ("django.template.loaders.cached.Loader", [
                    "django.template.loaders.filesystem.Loader",
                    "django.template.loaders.app_directories.Loader",
                ]),
            ],
            "context_processors": [...],
        },
    },
    {
        # Secondary: Jinja2 for analytics/admin templates (*.j2 files)
        "BACKEND": "django.template.backends.jinja2.Jinja2",
        "DIRS": [BASE_DIR / "jinja2_templates"],
        "APP_DIRS": False,
        "OPTIONS": {
            "environment": "config.jinja2.environment",
        },
    },
]

# config/jinja2.py — Jinja2 environment configuration
from jinja2 import Environment
from django.urls import reverse
from django.contrib.staticfiles.storage import staticfiles_storage


def environment(**options):
    env = Environment(**options)
    env.globals.update({
        "static":  staticfiles_storage.url,
        "url":     reverse,
    })
    return env

Conclusion

Django's template system is more than a way to write HTML with Python variables. It is a compile-once, render-many abstraction with a caching layer, a context injection pipeline, an extensible tag and filter system, and built-in security features that protect against the most common web vulnerabilities.

The key principles from this guide:

Enable the cached loader in production. It is the single most impactful template performance change you can make, and it costs nothing to configure. Avoid compiling each template every time it needs to be rendered.

Keep templates focused on presentation. Business logic belongs in views and services. Complex computations belong in Python, where they're testable, cacheable, and debuggable.

Prefetch everything the template touches. If your template iterates over a queryset and accesses related objects, those objects must be prefetched before the template renders. The template itself cannot trigger ORM optimisations — it can only trigger N+1 queries.

Use format_html in custom tags, never string formatting. Every custom tag that generates HTML must use format_html() or explicitly escape user-controlled values. Server-side template injection and XSS are the consequences of getting this wrong.

Cache context processors that do database work. A context processor that queries the database adds its cost to every single request across your entire site. Cache aggressively and invalidate on model save.

Template rendering is not where your application logic lives — but it is where all your application logic becomes visible to users. Make it fast, make it safe, and make it maintainable.

Table of Contents