Generally, you’ll store templates in files on your filesystem rather than using the low-level
Template API yourself. Save templates in a directory specified as a template directory. Django searches for template directories in a number of places, depending on your template loading settings (see “Loader types” below), but the most basic way of specifying template directories is by using the
Tell Django what your template directories are by using the
DIRS option in the
TEMPLATES setting in your settings file – or the
dirs argument of
Engine. This should be set to a list of strings that contain full paths to your template directories:
Your templates can go anywhere you want, as long as the directories and templates are readable by the Web server. They can have any extension you want, such as
.txt, or they can have no extension at all. Note that these paths should use Unix-style forward slashes, even on Windows.
By default, Django uses a filesystem-based template loader, but Django comes with a few other template loaders, which know how to load templates from other sources; the most commonly used of them, the apps loader, is described below.
filesystem.Loader Loads templates from the filesystem, according to
DIRS <TEMPLATES-DIRS>. This loader is enabled by default. However, it won’t find any templates until you set
DIRS <TEMPLATES-DIRS> to a non-empty list:
app_directories.Loader Loads templates from Django apps on the filesystem. For each app in
INSTALLED_APPS, the loader looks for a
templates subdirectory. If the directory exists, Django looks for templates in there. This means you can store templates with your individual apps. This also makes it easy to distribute Django apps with default templates. For example, for this setting:
get_template('foo.html') will look for
foo.html in these directories, in this order:
and will use the one it finds first.
The order of INSTALLED_APPS is significant!
For example, if you want to customize the Django admin, you might choose to override the standard
admin/base_site.html template, from
django.contrib.admin, with your own
You must then make sure that your
myproject.reviews comes before
django.contrib.admin’s will be loaded first and yours will be ignored.
Note that the loader performs an optimization when it first runs: it caches a list of which
INSTALLED_APPS packages have a
You can enable this loader simply by setting
The remaining template loaders are:
These loaders are disabled by default, but you can activate them by adding a
'loaders' option to your
DjangoTemplates backend in the
TEMPLATES setting or passing a
loaders argument to
Engine. Details on these advanced loaders, as well as building your own custom loader, can be found on the Django Project website.