Djangoの設定ファイルの基本を理解したい

こま（エンジニア）

Djangoの設定ファイルの基本を理解したい

こま（エンジニア）

2025.12.17

IT技術

Django

概要

Djangoのsettings.pyを毎回調べながら使っているので、もう少し仲良くなるためにドキュメントを読み直してみます。

ゴール

Djangoがデフォルトで生成する設定ファイル「settings.py」を読み解き、よく使う設定値がいつ・どこで・どのように参照されるのか
概要を復習することを目指します。

構成

settings.pyの中身を最初に見ておき、ブロック単位に何が書かれているか見ていきます。
すべて触れると長くなってしまうので、よく使うものに絞っておきます。

環境

Django: 5.2.8

settings.py

まずはデフォルト設定から、概観を掴んでおきます。

1"""
2Django settings for config project.
3
4Generated by 'django-admin startproject' using Django 5.2.8.
5
6For more information on this file, see
7https://docs.djangoproject.com/en/5.2/topics/settings/
8
9For the full list of settings and their values, see
10https://docs.djangoproject.com/en/5.2/ref/settings/
11"""
12
13from pathlib import Path
14
15# Build paths inside the project like this: BASE_DIR / 'subdir'.
16BASE_DIR = Path(__file__).resolve().parent.parent
17
18
19# Quick-start development settings - unsuitable for production
20# See https://docs.djangoproject.com/en/5.2/howto/deployment/checklist/
21
22# SECURITY WARNING: keep the secret key used in production secret!
23SECRET_KEY = 'django-insecure-zip##yovun391-2h05iwc=tx7z$w!al^n-l2#xlw%t8%kr-d#_'
24
25# SECURITY WARNING: don't run with debug turned on in production!
26DEBUG = True
27
28ALLOWED_HOSTS = []
29
30
31# Application definition
32
33INSTALLED_APPS = [
34    'django.contrib.admin',
35    'django.contrib.auth',
36    'django.contrib.contenttypes',
37    'django.contrib.sessions',
38    'django.contrib.messages',
39    'django.contrib.staticfiles',
40]
41
42MIDDLEWARE = [
43    'django.middleware.security.SecurityMiddleware',
44    'django.contrib.sessions.middleware.SessionMiddleware',
45    'django.middleware.common.CommonMiddleware',
46    'django.middleware.csrf.CsrfViewMiddleware',
47    'django.contrib.auth.middleware.AuthenticationMiddleware',
48    'django.contrib.messages.middleware.MessageMiddleware',
49    'django.middleware.clickjacking.XFrameOptionsMiddleware',
50]
51
52ROOT_URLCONF = 'config.urls'
53
54TEMPLATES = [
55    {
56        'BACKEND': 'django.template.backends.django.DjangoTemplates',
57        'DIRS': [],
58        'APP_DIRS': True,
59        'OPTIONS': {
60            'context_processors': [
61                'django.template.context_processors.request',
62                'django.contrib.auth.context_processors.auth',
63                'django.contrib.messages.context_processors.messages',
64            ],
65        },
66    },
67]
68
69WSGI_APPLICATION = 'config.wsgi.application'
70
71
72# Database
73# https://docs.djangoproject.com/en/5.2/ref/settings/#databases
74
75DATABASES = {
76    'default': {
77        'ENGINE': 'django.db.backends.sqlite3',
78        'NAME': BASE_DIR / 'db.sqlite3',
79    }
80}
81
82
83# Password validation
84# https://docs.djangoproject.com/en/5.2/ref/settings/#auth-password-validators
85
86AUTH_PASSWORD_VALIDATORS = [
87    {
88        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
89    },
90    {
91        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
92    },
93    {
94        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
95    },
96    {
97        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
98    },
99]
100
101
102# Internationalization
103# https://docs.djangoproject.com/en/5.2/topics/i18n/
104
105LANGUAGE_CODE = 'en-us'
106
107TIME_ZONE = 'UTC'
108
109USE_I18N = True
110
111USE_TZ = True
112
113
114# Static files (CSS, JavaScript, Images)
115# https://docs.djangoproject.com/en/5.2/howto/static-files/
116
117STATIC_URL = 'static/'
118
119# Default primary key field type
120# https://docs.djangoproject.com/en/5.2/ref/settings/#default-auto-field
121
122DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

ベース

BASE_DIR

1from pathlib import Path
2
3# settings.pyのparent.parentなので、settings.pyの親ディレクトリ。つまりプロジェクトディレクトリがBASE_DIRとなる
4# Build paths inside the project like this: BASE_DIR / 'subdir'.
5BASE_DIR = Path(__file__).resolve().parent.parent

Djangoプロジェクトの基準となるディレクトリを指します。

SECRET_KEY

When you create a new Django project using startproject, the settings.py file is generated automatically and gets a random SECRET_KEY value. This value is the key to securing signed data

SECRETKEYは、署名済みデータのキーとなる値です。
例えば、SECRETKEYがあることで、パスワードリセットURLがDjango側で発行されたものである。つまり不正に書き換えられていない正規のものであることを保証できるようです。

もしSECRET_KEYが漏洩すると、攻撃者に書き換えられた値もDjangoで安全なデータと扱われてしまうので、秘密の値として秘匿する必要があります。

参考

ALLOWED_HOSTS

Djangoアプリケーションを配信できるホスト名を配列形式で格納します。

ホスト名を限定することで、HTTPヘッダインジェクション攻撃を防げるようにしています。
参考

また、DEBUGオプションが有効な場合、自動でlocalhost関連の値を埋め込んでくれるようです。

Application definition

INSTALLED_APPS

A list of strings designating all applications that are enabled in this Django installation.

Djangoプロジェクトで有効になっているDjango appのリストを記述します。
記法はConfigクラスへの参照あるいは、Django appパッケージへの参照が書けます。Configクラスへの参照を書く形式が推奨されているようです。

補足: AppConfig

Configクラスの実装であるAppConfigクラスについてもう少し掘り下げておきます。

Application configuration objects store metadata for an application.

Django appのメタデータを格納するのがAppConfigクラスの責務のようです。
参考

これだけでは実体が見えづらいので、実際に使われているDjango app AuthのAuthConfigを見てみます。

重要なのは、以下のコードです。

1user_logged_in.connect(update_last_login, dispatch_uid="update_last_login")

Auth appはログイン関連の処理を司っているので、直近のログイン日を記録しておきたいです。
これをAppConfigのサブクラスであるAuthConfigで実装することで、Auth app全体で必要な振る舞いを定義しています。

普段はあまり意識することのないAppConfigですが、Django本体が提供するさまざまなDjango appの中で要所にフックとして使われている。
ということだけでも頭に入れておきたいです。

MIDDLEWARE

Djangoがリクエストを受け付けたとき・レスポンスを返すときに間に入って処理をするための仕組みがミドルウェアです。
セッションやCSRFなど、リクエストの前処理やレスポンスの後処理で挟みたいものを定義します。

ROOT_URLCONF

DjangoのURLディスパッチャがURLと対応するViewを探索するときのエントリーポイントを定義します。
settings.pyが置いてあるところに書かれたurls.pyを指定するのが一般的です。

TEMPLATES

Djangoのテンプレートエンジンに関連した設定値を定義します。
設定値BACKENDはテンプレートエンジンの実体・設定値OPTIONSに書かれたcontext_processorsは、テンプレートを描画するときに
参照するコンテキストという辞書を拡張するための機能を指します。

あとは設定値DIRSからテンプレートをプロジェクトルート直下から
配信する設定もよく使ったりします。

Database

DATABASES

A dictionary containing the settings for all databases to be used with Django. It is a nested dictionary whose contents map a database alias to a dictionary containing the options for an individual database.

データベースの設定を記述したものです。
辞書DATABASESはキーに各種データベースのエイリアスを持つ構造をとることで、Djangoアプリケーションで複数のデータベースを扱えるようになっています。

ひとまずはデータベースの接続設定とかを書いていると覚えておけば大丈夫そうです。

1DATABASES = {
2    "default": {
3        "ENGINE": "django.db.backends.postgresql",
4        "NAME": "mydatabase",
5        "USER": "mydatabaseuser",
6        "PASSWORD": "mypassword",
7        "HOST": "127.0.0.1",
8        "PORT": "5432",
9    }
10}

補足: ENGINEの役割

大体の設定値はデータベースの接続情報が含まれています。
しかし、キーENGINEはほかとは書き方が異なります。表記を見るに、Pythonパッケージへのパスを指していそうです。

django.db.backends.postgresqlと書かれている通り、Djangoはdjango.db.backendsというパッケージに各データベースのドライバとのインタフェースを持っています。
あとはPython向けのドライバのメソッドを、設定値に書かれた接続情報を介して呼び出せば、データベースを読み書きできるようになります。

Internationalization

LANGUAGE_CODE

A string representing the language code for this installation. This should be in standard language ID format.

文字通り、Djangoプロジェクトで取り扱う言語を指します。(例: ja-JP)
ここに指定できるのは、HTTPヘッダAccept-Languageのlanguageディレクティブに書かれるものと対応します。

Djangoでは、以下のリンクのリストを参照するよう言及されています。
参考

TIME_ZONE

データベースなどのタイムゾーン情報を書きます。タイムゾーン情報は下記のリンクで定義されています。
参考

ただ、実際はDjango公式からもリンクされているWikipediaを見た方が探しやすいかもしれないです。

USE_I18N

多言語対応をするかどうかのフラグです。無効にすると多少パフォーマンスに利があるようです。

USE_TZ

時刻を扱うときにタイムゾーンを参照するかどうかのフラグです。

このフラグの使い分けが気になりましたが、根深そうだったので、参考になりそうなリンクを貼るに留めておきます。
参考
実際のユースケースを考えてもやはり後方互換性のために残している感じがします。

Static files (CSS, JavaScript, Images)

Djangoの静的ファイル周りは少々ややこしいので、ローカル開発と本番で分けて考えます。

ローカル

ローカル開発でとくに意識するのは、設定値STATICFILES_DIRSです。

This setting defines the additional locations the staticfiles app will traverse if the FileSystemFinder finder is enabled, e.g. if you use the collectstatic or findstatic management command or use the static file serving view.

ローカル開発では、the static file serving viewと呼ばれる特殊なViewがデフォルトで有効になっています。
このおかげで、設定値STATICFILES_DIRに書かれたディレクトリおよび、Django appごとのstaticディレクトリから静的ファイルを探しに行ってくれます。

つまり、ローカル開発において、Djangoは以下のディレクトリを探索してくれます。

Django appのstaticディレクトリ
設定値STATICFILES_DIRに書かれたディレクトリ

本番

Djangoは静的ファイルをアプリケーションが動作するサーバとは別で配信したい、という思想を持っています。
これを実現するため、以下のような流れで静的ファイルを配信します。

collectstatic管理コマンドで設定値STATIC_ROOTに書かれたディレクトリへ静的ファイルを集約
もし静的ファイルを配信するサーバがDjangoアプリケーションサーバと異なるのであれば、設定値STATIC_ROOTに集められたファイルを転送
ユーザがページにアクセスしたら、設定値STATIC_URLに書かれた場所を見に行くことで、静的ファイルにたどり着けるようになる

これらの設定値はあくまで本番向けなので、ローカル開発では設定値STATIC_URLを変更しない限り、とくに意識しなくても開発できます。
静的ファイル周りは設定値が多く混乱しやすいところなので、ローカル開発・本番配信で境界を区切って捉えると、整理しやすくなるかもしれないです。

その他-設定ファイル読解に役立ったものメモ

設定ファイルについて調べていたとき、補助的な立ち位置で役立ってくれたコマンド周りについて整理しておきます。

django-admin vs manage.py

設定値をrepl的なやつで試したくなったときに、使い分けに少し迷ったので改めてまとめてみます。

In addition, manage.py is automatically created in each Django project. It does the same thing as django-admin but also sets the DJANGOSETTINGSMODULE environment variable so that it points to your project’s settings.py file.

単一のDjangoプロジェクトで作業する分には、manage.pyを使う方がDjango側でよしなに前準備をしてくれるようです。
manage.py自体に環境変数DJANGOSETTINGSMODULEを設定してくれる処理があるので、すぐにDjangoの機能を試せます。

参考