Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 77 ยท Templates

Template Inheritance and Includes

Stop repeating HTML. Learn Django's extends and block tags, block.super, include with parameters, template loaders and how to organize base templates in a project.

Every page on a website shares a frame: a header, a navigation bar, a footer, the same CSS and JavaScript links. Copying that frame into every template is the quickest way to create a maintenance nightmare, because a change to the menu then needs editing fifty files. Django solves this with template inheritance: you write the frame once in a base template with named holes, and each page extends the base and fills in only its holes.

For smaller repeated pieces (a comment box, a product card) Django offers the {% include %} tag. This lesson covers both, plus the loaders that find your template files. It assumes you know the basic syntax from Django Templates.

extends and block

A base template declares {% block name %}...{% endblock %} wherever child pages may put content. The text inside the block is the default, used when a child does not override it.

A child template begins with {% extends "base.html" %} and then defines blocks with the same names. Anything outside a block in a child is ignored, and {% extends %} must be the first tag in the file.

flowchart TD
    B["base.html<br/>title, content, footer blocks"] --> H["home.html<br/>fills title + content"]
    B --> P["blog/post.html<br/>fills title + content + footer"]
    P --> I["_byline.html<br/>included snippet"]

Pages extend one parent; small partials are pulled in with include.

{{ block.super }} inside a block prints the parent's version of that block, so a child can add to the parent's content instead of replacing it. That is perfect for page titles ({{ block.super }} - Contact) and for extra scripts.

Python A base template, two children and an include

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Study how the two children differ. home.html overrides title and content and leaves footer alone, so it inherits (c) 2026. blog/post.html uses {{ block.super }} in the title (giving "My Site - Templates") and in the footer (appending the author to the parent's footer text). The base template's <nav> appears in both without being repeated.

Some practical rules:

  • Name blocks by purpose (title, content, extra_head, scripts), and give the base template plenty of them. A good base has at least a title, a head extension point, the main content and a scripts block.
  • Inheritance can go several levels deep: base.html to base_two_column.html to the real page. Keep it to two or three levels, or the structure becomes hard to follow.
  • Blocks can be nested, and a child may override an inner block without touching the outer one.
  • Child templates cannot define the same block name twice.
  • A parent is chosen dynamically too: {% extends parent_template %} accepts a variable, which is occasionally useful for AJAX versus full-page responses.

include

{% include "name.html" %} renders another template in the current context and inserts the result. It is the right tool for a reusable fragment that belongs inside a block.

Two options matter:

  • with key=value: pass extra variables, as the byline did with author and date.
  • only: render the fragment with only the variables you pass, hiding the rest of the context. Use it to make partials self-contained and easier to reason about: {% include "card.html" with item=product only %}.

Prefix partial filenames with an underscore (_byline.html) as a convention so that people recognize them as fragments rather than full pages.

If you need the same markup with behavior (queries or computed values), an inclusion tag from Custom Template Tags and Filters is usually cleaner than a deep include with many with arguments.

Include versus extends: extends says "my page is a specialization of that frame", include says "insert this piece right here". Use both.

How Django finds templates

A template name like "blog/post.html" is just a string. A loader turns it into a template by searching somewhere. In a normal project two loaders are active:

  1. The filesystem loader searches the directories in TEMPLATES[0]["DIRS"], such as BASE_DIR / "templates".
  2. The app directories loader (enabled by APP_DIRS: True) searches the templates/ folder of every app in INSTALLED_APPS, in order.

The first match wins. That is why apps put their files in templates/<appname>/...: two apps both providing index.html would otherwise shadow each other, and the project can deliberately override an installed app's template by supplying the same path earlier in the search order. A typical layout:

TEXT
myproject/
  templates/              <- project level (DIRS)
    base.html
    404.html
  blog/
    templates/blog/       <- app level (APP_DIRS)
      post_list.html
      post_detail.html

Our live examples use locmem.Loader, which serves templates from a Python dictionary. It is meant for tests, and here it replaces the disk, which a browser cannot offer. The code that uses loaders does not care where they come from, so you can see the search order directly:

Python Loader order, select_template and TemplateDoesNotExist

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

page.html exists only in the second loader, but its {% extends 'layout.html' %} found the first loader's layout.html and used it, so the project's layout beat the app's. That is the same rule that lets a project override templates from third-party apps, including the admin.

select_template() takes a list of names and uses the first that exists, which is how ListView supports template_name_suffix fallbacks and how you can offer a specific template with a generic backup. A missing template raises TemplateDoesNotExist, and the error lists every place Django searched, which is the first thing to read when a page 500s with that message.

In production the loaders are wrapped by the cached loader (Django does this for you when DEBUG is False), so templates are compiled only once per process.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What must be true about {% extends %} in a child template?

    Django requires {% extends %} to be the first tag so it knows the parent before it processes the child's blocks.
  2. 2. What does {{ block.super }} output?

    block.super lets a child add to the parent's version of a block instead of replacing it.
  3. 3. Which tag renders a fragment with only the variables you list?

    include accepts with key=value arguments, and the only keyword stops the fragment from seeing the rest of the context.
  4. 4. Two apps each ship templates/index.html. Why does the convention templates/<app>/index.html matter?

    Loaders search directories in order and the first match wins. Namespacing by app avoids name collisions.
  5. 5. A child template defines text outside any block. What happens to it?

    Only blocks matter in a child that extends another template. Content outside blocks is not rendered.

Summary

  • A base template defines {% block %} holes; children use {% extends %} (first tag) and fill only the blocks they need.
  • {{ block.super }} includes the parent's block content, so children can add instead of replace.
  • {% include "x.html" with a=b only %} inserts a fragment; use underscore-prefixed names for partials.
  • Loaders search DIRS and each app's templates/ folder; the first match wins, so namespace app templates as templates/<app>/.
  • select_template() tries a list of names; TemplateDoesNotExist reports every location searched.
  • The locmem loader serves templates from a dictionary, which is handy for tests and live demos.

Next, extend the template language itself in Custom Template Tags and Filters.