Django 5.2 リリースノート

2025年4月2日

Django 5.2 へようこそ！

このリリースノートでは、 バージョン 5.2 の新機能 と、Django 5.1 以前からアップグレードする際に注意すべき、 後方互換性のない変更 について説明します。また、 一部の機能を非推奨 としました。

既存のプロジェクトをアップデートするときは、 Django の新しいバージョンへの更新 ガイドに従ってください。

Django 5.2 は 長期サポートリリース として設計されています。リリースから最低3年間はセキュリティアップデートを受けます。以前の LTS である Django 4.2 に対するサポートは2026年4月に終了します。

Python バージョン間の互換性

Django 5.2 は、Python 3.10, 3.11, 3.12, 3.13、および 3.14 (5.2.8 時点) をサポートしています。各シリーズの最新リリースのみが 強く推奨され 、公式にサポートされています。

Django 5.2 の新機能

shell における自動モデルインポート

shell 管理コマンドは、インストール済みのすべてのアプリからモデルを自動的にインポートするようになりました。 --verbosity フラグを 2 以上に設定すると、インポートされたオブジェクトの詳細をさらに表示できます。

Linux/macOS

$ python -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:

  from django.contrib.admin.models import LogEntry
  from django.contrib.auth.models import Group, Permission, User
  from django.contrib.contenttypes.models import ContentType
  from django.contrib.sessions.models import Session

Windows

...\> py -Wall manage.py shell --verbosity=2
6 objects imported automatically, including:

  from django.contrib.admin.models import LogEntry
  from django.contrib.auth.models import Group, Permission, User
  from django.contrib.contenttypes.models import ContentType
  from django.contrib.sessions.models import Session

この挙動は、自動インポートを追加または削除するように カスタマイズすることができます 。

複合主キー

新たに追加された django.db.models.CompositePrimaryKey により、複数のフィールドからなる主キーをテーブルに作成することができるようになりました。

複合主キーを使うには、モデルを定義する際に pk 属性を CompositePrimaryKey で設定します。

from django.db import models


class Release(models.Model):
    pk = models.CompositePrimaryKey("version", "name")
    version = models.IntegerField()
    name = models.CharField(max_length=20)

詳細は 複合主キー を参照してください。

BoundField のオーバーライドの簡素化

Prior to version 5.2, overriding Field.get_bound_field() was the only option to use a custom BoundField. Django now supports specifying the following attributes to customize form rendering:

• プロジェクト層で BaseRenderer.bound_field_class

• フォーム層で Form.bound_field_class

• フィールド層で Field.bound_field_class

例えば、 Form クラスの BoundField をカスタマイズするには、下記のように実装します。

from django import forms


class CustomBoundField(forms.BoundField):

    custom_class = "custom"

    def css_classes(self, extra_classes=None):
        result = super().css_classes(extra_classes)
        if self.custom_class not in result:
            result += f" {self.custom_class}"
        return result.strip()


class CustomForm(forms.Form):
    bound_field_class = CustomBoundField

    name = forms.CharField(
        label="Your Name",
        max_length=100,
        required=False,
        widget=forms.TextInput(attrs={"class": "name-input-class"}),
    )
    email = forms.EmailField(label="Your Email")

CustomForm インスタンスをレンダリングする際、下記の HTML が含まれます。

<div class="custom">
  <label for="id_name">Your Name:</label>
  <input type="text" name="name" class="name-input-class" maxlength="100" id="id_name">
</div>

<div class="custom">
  <label for="id_email">Your Email:</label>
  <input type="email" name="email" maxlength="320" required="" id="id_email">
</div>

この機能の更なる詳細は BoundField のカスタマイズ を参照してください。

マイナーな機能

django.contrib.admin

• admin/base.html テンプレートに新たなブロックとして extrabody <extrabody>`が追加されました。これにより、 ``</body>` タグの直前にカスタムコードを追加できるようになりました。

• URLField の値がリンクとしてレンダリングされるようになりました。

django.contrib.admindocs

• docstring 内のコンポーネントへのリンクは、 :role:`リンクテキスト <link>` という形式を用いることで、カスタムのリンクテキストをサポートするようになりました。詳細は ドキュメンテーション・ヘルパー を参照してください。

• モデルページ は、対応する閲覧または変更権限を持つユーザーのみに制限されるようになりました。

django.contrib.auth

• PBKDF2 パスワードハッシュに対するデフォルトのイテレーション回数が 870,000 から 1,000,000 に増加しました。

• a を先頭に持つ下記の非同期メソッドが新たに追加されました。

  • UserManager.acreate_user()

  • UserManager.acreate_superuser()

  • BaseUserManager.aget_by_natural_key()

  • User.aget_user_permissions()

  • User.aget_all_permissions()

  • User.aget_group_permissions()

  • User.ahas_perm()

  • User.ahas_perms()

  • User.ahas_module_perms()

  • ModelBackend.aauthenticate()

  • ModelBackend.aget_user_permissions()

  • ModelBackend.aget_group_permissions()

  • ModelBackend.aget_all_permissions()

  • ModelBackend.ahas_perm()

  • ModelBackend.ahas_module_perms()

  • RemoteUserBackend.aauthenticate()

  • RemoteUserBackend.aconfigure_user()

• 認証バックエンドは非同期実装を提供できるようになり、非同期の認証関数（例： aauthenticate() ）を呼び出す際にそれらが使用され、コンテキストスイッチが減って性能が向上します。詳細は 非同期インターフェースを追加する を参照してください。

• パスワードバリデータクラス に新たに get_error_message() 関数が追加されました。この関数をサブクラスでオーバーライドすることで、エラーメッセージをカスタマイズできるようになりました。

django.contrib.gis

• GDAL は、新たに追加された OGRGeometry.has_curve プロパティ、 OGRGeometry.get_linear_geometry() および OGRGeometry.get_curve_geometry() メソッドにより、曲線ジオメトリ CurvePolygon 、CompoundCurve 、CircularString 、MultiSurface 、 MultiCurve をサポートするようになりました。

• coveredby と covers ルックアップが MySQLをサポートするようになりました。

django.contrib.syndication

• すべての SyndicationFeed クラスが stylesheets 属性をサポートするようになりました。指定すると、与えられたリスト内の各スタイルシートごとに、文書の先頭へ <? xml-stylesheet ?> の処理命令が追加されます。詳しくは フィードのスタイルシート を参照してください。

データベースバックエンド

• MySQL の接続において、非推奨の文字セット utf8mb3 のエイリアスである utf8 ではなく、デフォルトで utf8mb4 文字セットを使用するようになりました。

• オラクルのバックエンドにおいて コネクションプール がサポートされました。これは、データベース設定の OPTIONS パートにおいて "pool" を設定することで使用できます。

デコレータ

• method_decorator() が非同期ビューメソッドをサポートするようになりました。

E メール

• EmailMessage.attachments と EmailMultiAlternatives.attachments のタプル要素は、通常のタプルではなく名前付きタプルになりました。

• EmailMultiAlternatives.alternatives は通常のタプルではなく名前付きタプルになりました。

• body_contains() メソッドが新たに追加されました。このメソッドは、メールの body および添付されたすべての text/* MIME タイプの代替コンテンツに指定したテキストが含まれているかどうかを示すブール値を返します。

エラー報告

• SafeExceptionReporterFilter.hidden_settings 属性は、値の名前に AUTH が含まれる場合にその値を機密情報として扱うようになりました。

フォーム

• ColorInput が新たに追加されました。このフォームウィジェットは <input type="color" ...> でレンダリングされ、 rrggbb 16進数フォーマットで色を入力できます。一部のブラウザでは視覚的なカラー選択インターフェースをこの入力タイプでサポートしています。

• SearchInput が新たに追加されました。このフォームウィジェットは <input type="search" ...> でレンダリングされ、検索文字列を入力できます。

• TelInput が新たに追加されました。このフォームウィジェットは <input type="tel" ...> でレンダリングされ、電話番号を入力できます。

• ErrorList に field_id 引数が追加され、エラーテンプレートの HTML に id 属性を追加できるようになりました。詳細は ErrorList.field_id を参照してください。

• BoundField に aria_describedby プロパティが追加され、テンプレート内でこの HTML 属性を簡単に使えるようになりました。

• スクリーンリーダー利用者のアクセシビリティを改善するため、フォームフィールドとそのエラーメッセージの関連付けに aria-describedby が使用されるようになりました。詳細は フォームエラーの表示方法 を参照してください。

• Script が新たに追加されました。このアセットオブジェクトはフォームメディア内の JavaScript にカスタム HTML 属性を追加するために利用できます。詳細は オブジェクトとしてのパス を参照してください。

管理コマンド

• runserver を実行すると、本番環境には不向きであることを示す警告が新たに表示されるようになりました。この警告は DJANGO_RUNSERVER_HIDE_WARNING 環境変数を "true" に設定することで非表示にできます。

• makemigrations および migrate コマンドに新たに Command.autodetector 属性が追加されました。この属性をサブクラスでオーバーライドすることで、カスタムの自動検出クラスを使用することができるようになります。

• BaseCommand.get_check_kwargs() メソッドが新たに追加されました。このメソッドをカスタムコマンドでオーバーライドすることで、データベース依存のチェックを有効化するなど、システムチェックの実行を制御できるようになります。

マイグレーション

• AlterConstraint が新たに no-op 操作として追加され、データベースの制約を削除・再作成しなくても制約を変更できるようになりました。

モデル

• QuerySet.values() と QuerySet.values_list() の使用時に生成される SELECT 句は、参照される式の指定順と一致するようになりました。従来は直感に反する一連の規則に基づいて順序が決定されていたため、 QuerySet.union() などのメソッドによるクエリ結合の結果が予測しにくいものとなっていました。

• GeneratedField を使用するモデル制約のバリデーションが新たにサポートされるようになりました。

• Expression.set_returning が新たに追加されました。この属性は式が集合を返す関数を含むことを指定し、サブクエリの評価を強制します。これは多くの Postgres における集合を返す関数で必要となります。

• SQLite において、無制限の VARCHAR 列がサポートされたため CharField.max_length が必須でなくなりました。

• PostgreSQL 17以降において、 QuerySet.explain() が memory と serialize オプションをサポートされるようになりました。

• データベース関数に JSONArray が新たに追加されました。この関数はフィールド名または式のリストを引数に取り、これらの値を含む JSON 配列を返します。

• Expression.allows_composite_expressions が新たに追加されました。この属性は複合式を許容するかどうかを指定し、例えば 複合主キー をサポートする際に使用されます。

Request と Response

• HttpResponse.content の文字列表現を提供する HttpResponse.text プロパティが追加されました。

• HttpRequest.get_preferred_type() が追加されました。この関数はクライアントが受け入れる優先メディアタイプを参照するために使用できます。

• HttpResponseRedirect と HttpResponsePermanentRedirect に preserve_request 引数が追加されました。この引数はそれぞれのクラスで HTTP ステータスコード 302/307 、 301/308 を使用するかどうかを決定します。

• redirect() に preserve_request 引数が追加されました。これにより、特定のステータスコードを用いたリダイレクト時に、ユーザーエージェントに対して HTTP メソッドと本文の再利用を指示できるようになりました。

シリアライズ (シリアル化)

• 各シリアライゼーション形式は、関数ではなく Deserializer クラスを定義するようになりました。これは、custom serialization format を定義する際の拡張性を高めるためです。

テンプレート

• simple_block_tag() デコレータが新たに追加されました。これにより、テンプレートの一部を受け取って使用できる単純なブロックタグの作成が可能となりました。

テスト

• Django のカスタムアサーションに由来するスタックフレームが非表示になりました。これにより、テスト失敗の出力が読みやすくなり、 test --pdb で失敗したテストメソッドに直接入れるようになります。

• fixtures と serialized_rollback=True で有効化されたマイグレーションから読み込まれたデータが TransactionTestCase.setUpClass() において利用可能になりました。

URL

• reverse() と reverse_lazy() に query および fragment キーワード引数を受け付けるようになりました。これにより、生成される URL にそれぞれクエリ文字列および／またはフラグメント識別子を追加できるようになりました。

ユーティリティ

• SafeString now returns NotImplemented in __add__ for non-string right-hand side values. This aligns with the str addition behavior and allows __radd__ to be used if available.

• format_html_join() は、マッピングのイテラブルを受け取り、その内容をキーワード引数として format_html() に渡せるようになりました。

5.2 における後方互換性のない変更

データベースバックエンド API

このセクションでは、サードパーティのデータベースバックエンドで必要になる可能性のある変更について説明します。

• Model._is_pk_set() メソッドが新たに追加され、モデルインスタンスの主キーが定義されているかどうかをチェックできるようになりました。

• BaseDatabaseOperations.adapt_decimalfield_value() は no-op 操作となり、単に与えられた値を返すようになりました。

django.contrib.gis

• PostGIS 3.0 に対するサポートが削除されました。

• GDAL 3.0 に対するサポートが削除されました。

PostgreSQL 13 に対するサポートの削除

PostgreSQL 13 へのアップストリームサポートは2025年11月に終了します。 Django 5.2 では PostgreSQL 14 以降をサポートします。

MySQL 接続における文字セットの既定値の変更

MySQL の接続は、非推奨の文字セット utf8mb3 のエイリアスである utf8 ではなく、デフォルトで utf8mb4 文字セットを使用するようになりました。レガシーなデータベースで必要な場合は、DATABASES 設定の OPTIONS で utf8mb3 を指定できます。

その他

• EmailMultiAlternatives.alternatives の追加は attach_alternative() メソッドでのみサポートされます。

• gettext の最小サポートバージョンが 0.15 から 0.19 に変更されました。

• HttpRequest.accepted_types はリクエストの Accept ヘッダーに基づき、クライアントの設定によってソートされるようになりました。

• 属性 UniqueConstraint.violation_error_code と UniqueConstraint.violation_error_message は指定されれば常に使用されるように変更されました。従来は UniqueConstraint.fields が指定され UniqueConstraint.condition が指定されない場合に無視されていました。

• コンテクストプロセッサである debug() はデフォルトのプロジェクトテンプレートには含まれなくなりました。

• 下記のメソッドは テンプレートコンテキストをレンダリングする 際の副作用を防ぐために、alters_data=True が設定されるようになりました。

  • UserManager.create_user()

  • UserManager.acreate_user()

  • UserManager.create_superuser()

  • UserManager.acreate_superuser()

  • QuerySet.create()

  • QuerySet.acreate()

  • QuerySet.bulk_create()

  • QuerySet.abulk_create()

  • QuerySet.get_or_create()

  • QuerySet.aget_or_create()

  • QuerySet.update_or_create()

  • QuerySet.aupdate_or_create()

• oracledb の最小サポートバージョンが 1.3.2 から 2.3.0 に変更されました。

• 1つの引数のみを許容するビルトインの集合関数 (Avg, Count, Max, Min, StdDev, Sum, and Variance) は引数の数が不適切な場合に TypeError を呼び出すようになりました。

5.2 で非推奨となった機能

その他

• django.contrib.staticfiles.finders.find() 関数の all 引数は非推奨となりました。代わりに find_all 引数を使用してください。

• django.contrib.auth.login() および django.contrib.auth.alogin() において user が None であるとき、 request.user や request.auser() にフォールバックする挙動は非推奨となりました。

• PostgreSQL 特有の集合を返す関数 django.contrib.postgres.aggregates.ArrayAgg 、 django.contrib.postgres.aggregates.JSONBAgg 、 django.contrib.postgres.aggregates.StringAgg``の ``ordering キーワード引数は非推奨となりました。代わりに order_by 引数を使用してください。

• aprocess_request() をオーバーライドせずに process_request() をオーバーライドする RemoteUserMiddleware のサブクラスのサポートが非推奨となりました。