{"title":"Django 5.2 release notes","version":"dev","locale":"en","docname":"releases/5.2","url":"/en/dev/releases/5.2/","canonical":"https://djangodocs.dev/en/dev/releases/5.2/","summary":"Welcome to Django 5.2! These release notes cover the new features, as well as some backwards incompatible changes you should be aware of when upgrading from…","html":"

Django 5.2 release notesLink to this heading#

\n

April 2, 2025

\n

Welcome to Django 5.2!

\n

These release notes cover the new features, as well as\nsome backwards incompatible changes you\nshould be aware of when upgrading from Django 5.1 or earlier. We’ve\nbegun the deprecation process for some features.

\n

See the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.

\n

Django 5.2 is designated as a long-term support release. It will receive security updates for at least\nthree years after its release. Support for the previous LTS, Django 4.2, will\nend in April 2026.

\n
\n

Python compatibilityLink to this heading#

\n

Django 5.2 supports Python 3.10, 3.11, 3.12, 3.13, and 3.14 (as of 5.2.8). We\nhighly recommend and only officially support the latest release of each\nseries.

\n
\n
\n

What’s new in Django 5.2Link to this heading#

\n
\n

Automatic models import in the shellLink to this heading#

\n

The shell management command now automatically imports models from\nall installed apps. You can view further details of the imported objects by\nsetting the --verbosity flag to 2 or more:

\n

Linux / macOS

Shell
$ python -Wall manage.py shell --verbosity=2\n6 objects imported automatically, including:\n\n  from django.contrib.admin.models import LogEntry\n  from django.contrib.auth.models import Group, Permission, User\n  from django.contrib.contenttypes.models import ContentType\n  from django.contrib.sessions.models import Session\n
\n

Windows

Windows
...\\> py -Wall manage.py shell --verbosity=2\n6 objects imported automatically, including:\n\n  from django.contrib.admin.models import LogEntry\n  from django.contrib.auth.models import Group, Permission, User\n  from django.contrib.contenttypes.models import ContentType\n  from django.contrib.sessions.models import Session\n
\n

This behavior can be customized to add\nor remove automatic imports.

\n
\n
\n

Composite Primary KeysLink to this heading#

\n

The new django.db.models.CompositePrimaryKey allows tables to be\ncreated with a primary key consisting of multiple fields.

\n

To use a composite primary key, when defining a model set the pk attribute\nto be a CompositePrimaryKey:

\n
Code
from django.db import models\n\n\nclass Release(models.Model):\n    pk = models.CompositePrimaryKey("version", "name")\n    version = models.IntegerField()\n    name = models.CharField(max_length=20)\n
\n

See Composite primary keys for more details.

\n
\n
\n

Simplified override of BoundFieldLink to this heading#

\n

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

\n\n

For example, to customize the BoundField of a Form class:

\n
Code
from django import forms\n\n\nclass CustomBoundField(forms.BoundField):\n\n    custom_class = "custom"\n\n    def css_classes(self, extra_classes=None):\n        result = super().css_classes(extra_classes)\n        if self.custom_class not in result:\n            result += f" {self.custom_class}"\n        return result.strip()\n\n\nclass CustomForm(forms.Form):\n    bound_field_class = CustomBoundField\n\n    name = forms.CharField(\n        label="Your Name",\n        max_length=100,\n        required=False,\n        widget=forms.TextInput(attrs={"class": "name-input-class"}),\n    )\n    email = forms.EmailField(label="Your Email")\n
\n

When rendering a CustomForm instance, the following HTML is included:

\n
Html
<div class="custom">\n  <label for="id_name">Your Name:</label>\n  <input type="text" name="name" class="name-input-class" maxlength="100" id="id_name">\n</div>\n\n<div class="custom">\n  <label for="id_email">Your Email:</label>\n  <input type="email" name="email" maxlength="320" required="" id="id_email">\n</div>\n
\n

See Customizing BoundField for more details about this feature.

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

  • The admin/base.html template now has a new block\nextrabody for adding custom code before the closing\n</body> tag.

    • \n

  • The value of a URLField now renders as a link.

    • \n
\n
\n
\n

django.contrib.admindocsLink to this heading#

\n
    \n

  • Links to components in docstrings now supports custom link text, using the\nformat :role:`link text <link>`. See documentation helpers for more details.

    • \n

  • The model pages are now restricted to\nusers with the corresponding view or change permissions.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

django.contrib.syndicationLink to this heading#

\n
    \n

  • All SyndicationFeed classes now support\na stylesheets attribute. If specified, an <? xml-stylesheet ?>\nprocessing instruction will be added to the top of the document for each\nstylesheet in the given list. See Feed stylesheets for more details.

    • \n
\n
\n
\n

Database backendsLink to this heading#

\n
    \n

  • MySQL connections now default to using the utf8mb4 character set,\ninstead of utf8, which is an alias for the deprecated character set\nutf8mb3.

    • \n

  • Oracle backends now support connection pools, by setting\n"pool" in the OPTIONS part of your database configuration.

    • \n
\n
\n
\n

DecoratorsLink to this heading#

\n\n
\n
\n

EmailLink to this heading#

\n\n
\n
\n

Error ReportingLink to this heading#

\n\n
\n
\n

FormsLink to this heading#

\n
    \n

  • The new ColorInput form widget is for entering a color\nin rrggbb hexadecimal format and renders as <input type="color" ...>.\nSome browsers support a visual color picker interface for this input type.

    • \n

  • The new SearchInput form widget is for entering search\nqueries and renders as <input type="search" ...>.

    • \n

  • The new TelInput form widget is for entering telephone\nnumbers and renders as <input type="tel" ...>.

    • \n

  • The new field_id argument for ErrorList allows an\nHTML id attribute to be added in the error template. See\nErrorList.field_id for details.

    • \n

  • An aria_describedby property is added to\nBoundField to ease use of this HTML attribute in templates.

    • \n

  • To improve accessibility for screen reader users aria-describedby is used\nto associate form fields with their error messages. See\nhow form errors are displayed for details.

    • \n

  • The new asset object Script is available for adding\ncustom HTML-attributes to JavaScript in form media. See\npaths as objects for more details.

    • \n
\n
\n
\n

Management CommandsLink to this heading#

\n
    \n

  • A new warning is displayed when running runserver, indicating that\nit is unsuitable for production. This warning can be suppressed by setting\nthe DJANGO_RUNSERVER_HIDE_WARNING environment variable to\n"true".

    • \n

  • The makemigrations and migrate commands have a new\nCommand.autodetector attribute for subclasses to override in order to use\na custom autodetector class.

    • \n

  • The new BaseCommand.get_check_kwargs() method can be overridden in\ncustom commands to control the running of system checks, e.g. to opt into\ndatabase-dependent checks.

    • \n
\n
\n
\n

MigrationsLink to this heading#

\n
    \n

  • The new operation AlterConstraint is a no-op operation that alters\nconstraints without dropping and recreating constraints in the database.

    • \n
\n
\n
\n

ModelsLink to this heading#

\n
    \n

  • The SELECT clause generated when using QuerySet.values() and\nQuerySet.values_list() now matches the specified order of the\nreferenced expressions. Previously, the order was based on a set of\ncounterintuitive rules which made query combination through methods such as\nQuerySet.union() unpredictable.

    • \n

  • Added support for validation of model constraints which use a\nGeneratedField.

    • \n

  • The new Expression.set_returning attribute specifies that the\nexpression contains a set-returning function, enforcing subquery evaluation.\nThis is necessary for many Postgres set-returning functions.

    • \n

  • CharField.max_length is no\nlonger required to be set on SQLite, which supports unlimited VARCHAR\ncolumns.

    • \n

  • QuerySet.explain() now supports the memory and serialize\noptions on PostgreSQL 17+.

    • \n

  • The new JSONArray database function\naccepts a list of field names or expressions and returns a JSON array\ncontaining those values.

    • \n

  • The new Expression.allows_composite_expressions attribute specifies\nthat the expression allows composite expressions, for example, to support\ncomposite primary keys.

    • \n
\n
\n
\n

Requests and ResponsesLink to this heading#

\n\n
\n
\n

SerializationLink to this heading#

\n
    \n

  • Each serialization format now defines a Deserializer class, rather than a\nfunction, to improve extensibility when defining a\ncustom serialization format.

    • \n
\n
\n
\n

TemplatesLink to this heading#

\n
    \n

  • The new simple_block_tag() decorator enables\nthe creation of simple block tags, which can accept and use a section of the\ntemplate.

    • \n
\n
\n
\n

TestsLink to this heading#

\n
    \n

  • Stack frames from Django’s custom assertions are now hidden. This makes test\nfailures easier to read and enables test --pdb to directly enter\ninto the failing test method.

    • \n

  • Data loaded from fixtures and from\nmigrations enabled with serialized_rollback=True are now available during\nTransactionTestCase.setUpClass().

    • \n
\n
\n
\n

URLsLink to this heading#

\n
    \n

  • reverse() and reverse_lazy() now accept\nquery and fragment keyword arguments, allowing the addition of a\nquery string and/or fragment identifier in the generated URL, respectively.

    • \n
\n
\n
\n

UtilitiesLink to this heading#

\n
    \n

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

    • \n

  • format_html_join() now supports taking an iterable\nof mappings, passing their contents as keyword arguments to\nformat_html().

    • \n
\n
\n
\n
\n
\n

Backwards incompatible changes in 5.2Link to this heading#

\n
\n

Database backend APILink to this heading#

\n

This section describes changes that may be needed in third-party database\nbackends.

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

Dropped support for PostgreSQL 13Link to this heading#

\n

Upstream support for PostgreSQL 13 ends in November 2025. Django 5.2 supports\nPostgreSQL 14 and higher.

\n
\n
\n

Changed MySQL connection character set defaultLink to this heading#

\n

MySQL connections now default to using the utf8mb4 character set, instead\nof utf8, which is an alias for the deprecated character set utf8mb3.\nutf8mb3 can be specified in the OPTIONS part of the DATABASES\nsetting, if needed for legacy databases.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 5.2Link to this heading#

\n
\n

MiscellaneousLink to this heading#

\n\n
\n
","rootId":"django-5-2-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 5.2","anchor":"what-s-new-in-django-5-2","children":[{"title":"Automatic models import in the shell","anchor":"automatic-models-import-in-the-shell","children":[]},{"title":"Composite Primary Keys","anchor":"composite-primary-keys","children":[]},{"title":"Simplified override of BoundField","anchor":"simplified-override-of-boundfield","children":[]},{"title":"Minor features","anchor":"minor-features","children":[{"title":"django.contrib.admin","anchor":"django-contrib-admin","children":[]},{"title":"django.contrib.admindocs","anchor":"django-contrib-admindocs","children":[]},{"title":"django.contrib.auth","anchor":"django-contrib-auth","children":[]},{"title":"django.contrib.gis","anchor":"django-contrib-gis","children":[]},{"title":"django.contrib.syndication","anchor":"django-contrib-syndication","children":[]},{"title":"Database backends","anchor":"database-backends","children":[]},{"title":"Decorators","anchor":"decorators","children":[]},{"title":"Email","anchor":"email","children":[]},{"title":"Error Reporting","anchor":"error-reporting","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Migrations","anchor":"migrations","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Serialization","anchor":"serialization","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"URLs","anchor":"urls","children":[]},{"title":"Utilities","anchor":"utilities","children":[]}]}]},{"title":"Backwards incompatible changes in 5.2","anchor":"backwards-incompatible-changes-in-5-2","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.gis","anchor":"id1","children":[]},{"title":"Dropped support for PostgreSQL 13","anchor":"dropped-support-for-postgresql-13","children":[]},{"title":"Changed MySQL connection character set default","anchor":"changed-mysql-connection-character-set-default","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 5.2","anchor":"features-deprecated-in-5-2","children":[{"title":"Miscellaneous","anchor":"id2","children":[]}]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/5.2.1","title":"Django 5.2.1 release notes","url":"/en/dev/releases/5.2.1/"},"next":{"docname":"releases/5.1.15","title":"Django 5.1.15 release notes","url":"/en/dev/releases/5.1.15/"},"formats":{"html":"/en/dev/releases/5.2/","markdown":"/en/dev/releases/5.2.md","json":"/en/dev/releases/5.2.json"},"source":"https://github.com/django/django/blob/main/docs/releases/5.2.txt","official":"https://docs.djangoproject.com/en/dev/releases/5.2/","inVersions":["dev","6.1","6.0","5.2"],"inLocales":["en"]}