できない.dev

Django で「TemplateDoesNotExist」が出てテンプレートを読み込めない

TemplateDoesNotExist は、テンプレート名がどの探索先にも見つからないときに出る。
エラー画面の「Template-loader postmortem」に探したパスが並ぶので、DIRS・APP_DIRS・INSTALLED_APPS と配置を突き合わせる。

公開: 更新:

症状できない · exit 1
python render.py base.html
  /usr/local/lib/python3.12/site-packages/django/contrib/admin/templates/base.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/auth/templates/base.html (Source does not exist)
django.template.exceptions.TemplateDoesNotExist: base.html
解決後できた · exit 0
python render.py base.html
<h1>できない.dev</h1>

2026-10-24 に python:3.12(Django 5.2.18) で実際に打って取った出力。検証環境の詳細

要約

Django のテンプレートは、settings.py の TEMPLATES に書いた探索先を順に調べて見つける。
どこにも無ければ次の例外になる。

django.template.exceptions.TemplateDoesNotExist: index.html

DEBUG = True ならエラー画面に「Template-loader postmortem」が表示され、ローダーごとに実際に探したパスと Source does not exist が並ぶ。
置いたつもりの場所がこの一覧に無ければ、探索先の設定が足りない。
一覧にあるのに見つからなければ、ファイル名かディレクトリの階層が違う。

実行例

DIRS が空のままだと base.html が見つからず、探したパスが並んだあとで終了コード 1 の例外になった。
BASE_DIR / 'templates' を登録すると読み込めた。
アプリ側は blog/templates/blog/ に置き直すまで、blog/index.html が見つからなかった。
継承元の名前を間違えたときは、例外に出る名前も継承元の layouts/base.html になった。

$ grep -n DIRS mysite/settings.py
58:        'DIRS': [],
59:        'APP_DIRS': True,
$ python render.py base.html
  /usr/local/lib/python3.12/site-packages/django/contrib/admin/templates/base.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/auth/templates/base.html (Source does not exist)
django.template.exceptions.TemplateDoesNotExist: base.html
$ echo $?
1
$ grep -n DIRS mysite/settings.py
58:        'DIRS': [BASE_DIR / 'templates'],
59:        'APP_DIRS': True,
$ python render.py base.html
<h1>できない.dev</h1>
$ echo $?
0
$ python render.py blog/index.html
  /tmp/tmp.aSNY0xdGwL/templates/blog/index.html (Source does not exist)
  /tmp/tmp.aSNY0xdGwL/blog/templates/blog/index.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/admin/templates/blog/index.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/auth/templates/blog/index.html (Source does not exist)
django.template.exceptions.TemplateDoesNotExist: blog/index.html
$ echo $?
1
$ find blog/templates -type f
blog/templates/blog/index.html
$ python render.py blog/index.html
<h1>ブログ</h1>
$ echo $?
0
$ python render.py blog/index.html
  /tmp/tmp.aSNY0xdGwL/templates/layouts/base.html (Source does not exist)
  /tmp/tmp.aSNY0xdGwL/blog/templates/layouts/base.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/admin/templates/layouts/base.html (Source does not exist)
  /usr/local/lib/python3.12/site-packages/django/contrib/auth/templates/layouts/base.html (Source does not exist)
django.template.exceptions.TemplateDoesNotExist: layouts/base.html
$ echo $?
1
$ python render.py blog/index.html
<h1>ブログ</h1>
$ echo $?
0

— 2026-10-24 時点の出力

検証環境Python 3.12.15 / Git 2.47.3 / Django 5.2.18 / 2026-10-24 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.15
  • Git 2.47.3
  • Django 5.2.18

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. プロジェクト共通のディレクトリを DIRS に登録する

# settings.py
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            # startproject が生成した context_processors はそのまま残す
        },
    },
]

BASE_DIR は startproject が settings.py の先頭で定義しており、manage.py のあるディレクトリを指す。

2. アプリを登録し APP_DIRS を有効にする

アプリ内のテンプレートを使うなら、アプリを INSTALLED_APPS に入れ、APP_DIRS を True にする。

INSTALLED_APPS = [
    "blog.apps.BlogConfig",
    # ...
]

3. アプリ名のサブディレクトリで名前空間を切る

公式ドキュメントは、テンプレートをアプリごとのサブディレクトリに整理する方法を推奨している。

blog/
└── templates/
    └── blog/
        └── index.html
from django.shortcuts import render
 
def index(request):
    return render(request, "blog/index.html")

名前空間を切らずに複数のアプリへ同じ index.html を置くと、INSTALLED_APPS で先に並んだアプリのものが使われる。
エラーにならないまま別のテンプレートが表示されるので、最初から階層を分けておく。

4. 例外に出ている名前を読む

例外やエラー画面の見出しに出ているテンプレート名が、ビューで指定した名前と違うかを確認する。
違うなら、そのテンプレートを {% extends %} か {% include %} している箇所が原因だ。

{% extends "base.html" %}

継承元を templates/base.html に置くか、実際の配置に合わせて "layouts/base.html" のように名前を直す。

よくある原因

  1. DIRS が空になっている。
    startproject が作る設定は "DIRS": [] なので、プロジェクト直下に templates/ を作っただけでは探索されない。
  2. アプリのディレクトリが探索対象から外れている。
    APP_DIRS が True のとき、Django は INSTALLED_APPS に登録された各アプリの templates サブディレクトリを探す。
    アプリが未登録、または APP_DIRS が False だとそこは見られない。
  3. 名前空間の階層が合っていない。
    render() に渡す名前は、探索先ディレクトリからの相対パスだ。
    blog/templates/index.html に置いたファイルは "index.html" で見つかり、"blog/index.html" では見つからない。
  4. 継承元や部品のテンプレートが無い。
    {% extends "base.html" %} の base.html が無い場合、例外に出る名前は render() に渡した名前ではなく base.html になる。