{"title":"How to override templates","version":"4.1","locale":"en","docname":"howto/overriding-templates","url":"/en/4.1/howto/overriding-templates/","canonical":"https://djangodocs.dev/en/4.1/howto/overriding-templates/","summary":"In your project, you might want to override a template in another Django application, whether it be a third-party application or a contrib application such as…","html":"

How to override templatesLink to this heading#

\n

In your project, you might want to override a template in another Django\napplication, whether it be a third-party application or a contrib application\nsuch as django.contrib.admin. You can either put template overrides in your\nproject’s templates directory or in an application’s templates directory.

\n

If you have app and project templates directories that both contain overrides,\nthe default Django template loader will try to load the template from the\nproject-level directory first. In other words, DIRS\nis searched before APP_DIRS.

\n\n
\n

Overriding from the project’s templates directoryLink to this heading#

\n

First, we’ll explore overriding templates by creating replacement templates in\nyour project’s templates directory.

\n

Let’s say you’re trying to override the templates for a third-party application\ncalled blog, which provides the templates blog/post.html and\nblog/list.html. The relevant settings for your project would look like:

\n
Code
from pathlib import Path\n\nBASE_DIR = Path(__file__).resolve().parent.parent\n\nINSTALLED_APPS = [\n    ...,\n    'blog',\n    ...,\n]\n\nTEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [BASE_DIR / 'templates'],\n        'APP_DIRS': True,\n        ...\n    },\n]\n
\n

The TEMPLATES setting and BASE_DIR will already exist if you\ncreated your project using the default project template. The setting that needs\nto be modified is DIRS.

\n

These settings assume you have a templates directory in the root of your\nproject. To override the templates for the blog app, create a folder\nin the templates directory, and add the template files to that folder:

\n
None
templates/\n    blog/\n        list.html\n        post.html\n
\n

The template loader first looks for templates in the DIRS directory. When\nthe views in the blog app ask for the blog/post.html and\nblog/list.html templates, the loader will return the files you just created.

\n
\n
\n

Overriding from an app’s template directoryLink to this heading#

\n

Since you’re overriding templates located outside of one of your project’s\napps, it’s more common to use the first method and put template overrides in a\nproject’s templates folder. If you prefer, however, it’s also possible to put\nthe overrides in an app’s template directory.

\n

First, make sure your template settings are checking inside app directories:

\n
Code
TEMPLATES = [\n    {\n        ...,\n        'APP_DIRS': True,\n        ...\n    },\n]\n
\n

If you want to put the template overrides in an app called myapp and the\ntemplates to override are named blog/list.html and blog/post.html,\nthen your directory structure will look like:

\n
None
myapp/\n    templates/\n        blog/\n            list.html\n            post.html\n
\n

With APP_DIRS set to True, the template\nloader will look in the app’s templates directory and find the templates.

\n
\n
\n

Extending an overridden templateLink to this heading#

\n

With your template loaders configured, you can extend a template using the\n{% extends %} template tag whilst at the same time overriding\nit. This can allow you to make small customizations without needing to\nreimplement the entire template.

\n

For example, you can use this technique to add a custom logo to the\nadmin/base_site.html template:

\n
\n
templates/admin/base_site.html
\n
Django template
 {% extends "admin/base_site.html" %}\n\n {% block branding %}\n     <img src="link/to/logo.png" alt="logo">\n     {{ block.super }}\n {% endblock %}\n
\n
\n

Key points to note:

\n\n

This technique works because the template loader does not consider the already\nloaded override template (at templates/admin/base_site.html) when\nresolving the extends tag. Combined with block.super it is a powerful\ntechnique to make small customizations.

\n
","rootId":"how-to-override-templates","toc":[{"title":"Overriding from the project’s templates directory","anchor":"overriding-from-the-project-s-templates-directory","children":[]},{"title":"Overriding from an app’s template directory","anchor":"overriding-from-an-app-s-template-directory","children":[]},{"title":"Extending an overridden template","anchor":"extending-an-overridden-template","children":[]}],"breadcrumbs":[{"docname":"howto/index","title":"“How-to” guides","url":"/en/4.1/howto/"}],"prev":{"docname":"howto/outputting-pdf","title":"How to create PDF files","url":"/en/4.1/howto/outputting-pdf/"},"next":{"docname":"howto/static-files/index","title":"How to manage static files (e.g. images, JavaScript, CSS)","url":"/en/4.1/howto/static-files/"},"formats":{"html":"/en/4.1/howto/overriding-templates/","markdown":"/en/4.1/howto/overriding-templates.md","json":"/en/4.1/howto/overriding-templates.json"},"source":"https://github.com/django/django/blob/stable/4.1.x/docs/howto/overriding-templates.txt","official":"https://docs.djangoproject.com/en/4.1/howto/overriding-templates/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11"],"inLocales":["en","zh-hans","fr","ja","id","it","pt-br","ko","es","el","pl"]}