Django 6.1 release notes

August 5, 2026

Welcome to Django 6.1!

These release notes cover the new features, as well as some backwards incompatible changes you'll want to be aware of when upgrading from Django 6.0 or earlier. We've begun the deprecation process for some features.

See the /howto/upgrade-version guide if you're updating an existing project.

Mainstream support is expected to end in April 2027. Extended support is expected to end in December 2027.

Python compatibility

Django 6.1 supports Python 3.12, 3.13, and 3.14. We highly recommend, and only officially support, the latest release of each series.

What's new in Django 6.1

Model field fetch modes

The on-demand fetching behavior of model fields is now configurable with fetch modes. These modes allow you to control how Django fetches data from the database when an unfetched field is accessed.

Django provides three fetch modes:

1. FETCH_ONE, the default, fetches the missing field for the current instance only. This mode represents Django's existing behavior.

2. FETCH_PEERS fetches a missing field for all instances that came from the same ~django.db.models.query.QuerySet.

   This mode works like an on-demand prefetch_related(). It can reduce most cases of the "N+1 queries problem" to two queries without any work to maintain a list of fields to prefetch.

3. FETCH_RAISE raises a ~django.core.exceptions.FieldFetchBlocked exception.

   This mode can prevent unintentional queries in performance-critical sections of code.

Use the new method .QuerySet.fetch_mode to set the fetch mode for model instances fetched by the QuerySet:

from django.db import models

books = Book.objects.fetch_mode(models.FETCH_PEERS)
for book in books:
    print(book.author.name)

Despite the loop accessing the author foreign key on each instance, the FETCH_PEERS fetch mode will make the above example perform only two queries:

1. Fetch all books.

2. Fetch associated authors.

See fetch modes for more details.

Database-level delete options for ForeignKey.on_delete

.ForeignKey.on_delete now supports database-level delete options:

• ~django.db.models.DB_CASCADE

• ~django.db.models.DB_SET_NULL

• ~django.db.models.DB_SET_DEFAULT

These options handle deletion logic entirely within the database, using the SQL ON DELETE clause. They are thus more efficient than the existing Python-level options, as Django does not need to load objects before deleting them. As a consequence, the ~django.db.models.DB_CASCADE option does not trigger the pre_delete or post_delete signals.

Mailers

The new MAILERS setting supports configuring multiple email backends with different options, similar to existing mechanisms for CACHES, DATABASES, STORAGES, and TASKS:

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {"host": "smtp.example.com", "use_tls": True},
    },
    "marketing": {
        "BACKEND": "example.third.party.EmailBackend",
        "OPTIONS": {"region": "africa-1"},
    },
}

You can select a mailer with the new using argument to email sending functions, or obtain an email backend instance with mail.mailers[alias]. See /topics/email for more details.

MAILERS is not yet enabled by default in existing projects. It will replace EMAIL_BACKEND and related EMAIL_* settings in Django 7.0. Until then, the older settings will continue to work but will issue deprecation warnings: see the list of email deprecations below.

You can opt into the new feature at any time before Django 2028; see migrating-to-mailers. To ease the transition, mail.mailers["default"] works with either MAILERS or the deprecated EMAIL_BACKEND setting defined. The deprecated ~django.core.mail.get_connection function will also return an instance of the default mailer when MAILERS is defined.

Minor features

django.contrib.admin

• The admin site login view now redirects authenticated users to the next URL, if available, instead of always redirecting to the admin index page.

• The admin's FilteredSelectMultiple widget now uses <optgroup>s to preserve named groups (e.g. choices=[("Group", [("1", "Item")]), ...]).

• When .ModelAdmin.list_select_related is False (the default), the change list now selects only the foreign key fields specified in .ModelAdmin.list_display, rather than all foreign key fields. This should improve performance for models with many foreign key fields.

• The ~django.contrib.admin.ModelAdmin.delete_confirmation_max_display option allows customizing how many objects are displayed on admin delete confirmation pages and inline protected deletion errors before the remainder is truncated. The default is None (no truncation).

• In order to improve accessibility of the admin change forms:

  • Form fields are now shown below their respective labels instead of next to them.

  • Help text is now shown after the field label and before the field input.

  • Validation errors are now shown after the help text and before the field input.

  • Checkboxes are an exception to the above changes and continue to be displayed in their original layout.

• ~django.contrib.admin.ModelAdmin.list_display now uses boolean icons for boolean fields on related models.

• The new location keyword argument of the ~django.contrib.admin.action decorator specifies which admin views the action is available on. The action is available on the admin change list page by default. It can also be available on the admin change form. See admin-action-availability for details.

• The new description_plural keyword argument of the ~django.contrib.admin.action decorator specifies a human-readable description for actions on the admin change list page. Defaults to the description value. This is useful when the action is available on both the admin change list and admin change form.

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 1,200,000 to 1,500,000.

• .Permission.name and .Permission.codename values are now renamed when renaming models via a migration.

• The new .Permission.user_perm_str property returns the string suitable to use with .User.has_perm.

django.contrib.gis

• The isempty lookup and IsEmpty() database function are now supported on SpatiaLite.

• The new num_dimensions lookup and NumDimensions() database function allow filtering geometries by the number of dimensions on PostGIS and SpatiaLite.

• ~django.contrib.gis.forms.widgets.OpenLayersWidget is now based on OpenLayers 10.9.0 (previously 7.2.2).

django.contrib.postgres

• inspectdb now introspects ~django.contrib.postgres.fields.HStoreField when psycopg 3.2+ is installed and django.contrib.postgres is in INSTALLED_APPS.

• ~django.contrib.postgres.constraints.ExclusionConstraint now supports the Hash index type.

django.contrib.sessions

• ~django.contrib.sessions.backends.base.SessionBase now supports boolean evaluation via ~django.contrib.sessions.backends.base.SessionBase.__bool__.

CSP

• The new csp_nonce_attr template tag renders the CSP nonce attribute on <script> and <link> elements, or renders a ~django.forms.Media object's assets with the nonce applied, when the ~django.template.context_processors.csp context processor is configured. See csp-nonce for details.

• A new security.W027 system check warns when ~django.middleware.csp.ContentSecurityPolicyMiddleware is enabled with CSP.NONCE in a CSP policy but django.template.context_processors.csp is not configured.

• CSP nonce attributes are now added on <script>, <style>, and <link> elements in admin templates and all built-in templates when the ~django.template.context_processors.csp context processor is configured. See csp-nonce-config for setup instructions.

Email

• A new mail.E001 deployment-only system check prevents using one of Django's email backends that is not intended for production use in the 'default' MAILERS entry.

• A new mail.W001 system check warns when MAILERS is defined but does not include a 'default' entry.

Forms

• The new asset object ~django.forms.Stylesheet is available for adding custom HTML-attributes to stylesheet links in form media. See paths as objects for more details.

• The new constant django.db.models.fields.BLANK_CHOICE_LABEL defines a more accessible and translatable default label for the blank choice in forms, which is appended to most choices lists. The transitional setting USE_BLANK_CHOICE_DASH allows you to revert back to the old default label.

• ~django.forms.FilePathField now provides a ~django.forms.FilePathField.set_choices method to scan the directory at ~django.forms.FilePathField.path and refresh the field's choices. This allows per-request refreshing when called in a form's __init__().

Generic Views

• The new .RedirectView.preserve_request attribute allows preserving the HTTP method and body during redirects, using 307/308 status codes instead of 302/301.

Management Commands

• Management commands now set ~argparse.ArgumentParser's suggest_on_error argument to True by default on Python 3.14, enabling suggestions for incorrectly typed subcommand names and argument choices.

• The loaddata command now calls ~django.db.models.signals.m2m_changed signals with raw=True when loading fixtures.

• The sendtestemail command now supports a --using option to specify the MAILERS alias.

Models

• .QuerySet.in_bulk now supports chaining after .QuerySet.values and .QuerySet.values_list.

• The new ~django.db.models.JSONNull expression provides an explicit way to represent the JSON scalar null. It can be used when saving a top-level ~django.db.models.JSONField value, or querying for top-level or nested JSON null values. See storing-and-querying-for-none for usage examples and some caveats.

• DecimalField.max_digits and DecimalField.decimal_places are no longer required to be set on Oracle, PostgreSQL, and SQLite.

• ~django.db.models.JSONField now supports negative array indexing on Oracle 21c+.

• The new ~django.db.models.functions.UUID4 and ~django.db.models.functions.UUID7 database functions were added.

• ~django.db.models.GeneratedField now supports virtual columns (~django.db.models.GeneratedField.db_persist set to False) on Postgres 18+ and stored columns (~django.db.models.GeneratedField.db_persist set to True) on Oracle 23ai/26ai (23.7+).

• The ~django.db.models.signals.m2m_changed signal now receives a raw argument.

• ~django.db.models.StringAgg now supports distinct=True on SQLite when using the default delimiter Value(",") only.

• The new .QuerySet.totally_ordered property returns True if the ~django.db.models.query.QuerySet is ordered and the ordering is deterministic.

• The new ~django.db.models.BitAnd, ~django.db.models.BitOr, and ~django.db.models.BitXor aggregates return the bitwise AND, OR, XOR, respectively. These aggregates were previously included only in contrib.postgres.

• django.db.models.BinaryField now validates Base64 input strictly. Invalid Base64 strings now raise ValidationError instead of being silently accepted.

Requests and Responses

• HttpRequest.multipart_parser_class can now be customized to use a different multipart parser class.

• ~django.http.HttpResponseRedirect (and its subclasses), as well as the ~django.shortcuts.redirect shortcut, now accept a max_length parameter to override the default maximum URL length limit.

Security

• Signed cookies now use an unambiguous salt derivation by default. Set SIGNED_COOKIE_LEGACY_SALT_FALLBACK to True to continue accepting legacy signed cookies.

Serialization

• Subclasses of models defining the natural_key() method can now opt out of natural key serialization by overriding the method to return an empty tuple: (). This ensures primary keys are serialized when using dumpdata --natural-primary.

• The XML deserializer now raises ~django.core.exceptions.SuspiciousOperation when it encounters unexpected nested tags.

Tasks

• The ~django.tasks.task decorator now accepts **kwargs, which are forwarded to the backend's ~django.tasks.backends.base.BaseTaskBackend.task_class.

• ~django.tasks.Task and ~django.tasks.TaskResult instances can now be pickled and unpickled.

Tests

• ~django.test.SimpleTestCase.assertContains and ~django.test.SimpleTestCase.assertNotContains can now be called multiple times on the same ~django.http.StreamingHttpResponse. Previously, they would consume the streaming response's content, causing subsequent calls to fail.

Utilities

• ~django.utils.dateparse.parse_duration now supports ISO 8601 time periods expressed in weeks (PnW).

Backwards incompatible changes in 6.1

Database backend API

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

• The DatabaseOperations.adapt_durationfield_value() hook is added. If the database has native support for DurationField, override this method to simply return the value.

• The DatabaseIntrospection.get_relations() should now return a dictionary with 3-tuples containing (field_name_other_table, other_table, db_on_delete) as values. db_on_delete is one of the database-level delete options e.g. ~django.db.models.DB_CASCADE.

• Set the new DatabaseFeatures.supports_inspectdb attribute to False if the management command isn't supported.

• The DatabaseFeatures.prohibits_dollar_signs_in_column_aliases feature flag is removed.

• The DatabaseOperations.binary_placeholder_sql() method now expects a query compiler as an extra positional argument and should return a two-elements tuple composed of an SQL format string and a tuple of associated parameters.

• The BaseSpatialOperations.get_geom_placeholder() method is renamed to get_geom_placeholder_sql and is expected to return a two-elements tuple composed of an SQL format string and a tuple of associated parameters.

• Set the new DatabaseFeatures.supports_bit_aggregations attribute to False if the database doesn't support bitwise aggregations.

django.contrib.admin

• The wide class is removed, as it was made obsolete by the new layout.

• The object-tools block is hoisted out of the content block in forms.

• The undocumented InclusionAdminNode.__init__() now takes the template tag name as the first positional argument.

• The undocumented ChangeList.has_related_field_in_list_display() method has been replaced with ChangeList.get_select_related_fields().

django.contrib.auth

• Under ASGI, ~django.contrib.auth.middleware.RemoteUserMiddleware no longer prefixes HTTP_ when looking up custom values in request.META. For example, to send -H "AuthUser: ...", the header attribute should be HTTP_AUTHUSER. This restores the behavior prior to Django 5.2. (The default value of REMOTE_USER is not affected.)

django.contrib.gis

• Support for PostGIS 3.1 is removed.

• Support for GEOS 3.8 and 3.9 is removed.

• Support for GDAL 3.1 and 3.2 is removed.

django.contrib.postgres

• Top-level elements set to None in an ~django.contrib.postgres.fields.ArrayField with a ~django.db.models.JSONField base field are now saved as SQL NULL instead of the JSON null primitive. This matches the behavior of a standalone ~django.db.models.JSONField when storing None values.

Email

• Providing fail_silently=True, auth_user, or auth_password to mail sending functions (such as ~django.core.mail.send_mail) while also providing a connection now raises a TypeError.

• The undocumented EmailMessage.get_connection() method is no longer used. Defining it in a subclass or trying to call it now causes an error.

• .EmailMessage.send no longer sets the connection property on the EmailMessage. (This behavior was never documented. The send() method will still use a connection that is set on the message before sending.)

• .EmailMessage.message now raises a ValueError if Bcc is included in the headers argument or extra_headers attribute. Use the bcc argument instead.

Models

• The iexact=None lookup on ~django.db.models.JSONField key transforms now matches JSON null, to match the behavior of exact=None on key transforms. Previously, it was interpreted as an isnull lookup.

• ~.QuerySet.first and ~.QuerySet.last no longer order by the primary key when a QuerySet's ordering has been forcibly cleared by calling ~.QuerySet.order_by with no arguments.

• As default model ordering is now applied to combined querysets, ~.QuerySet.union, ~.QuerySet.difference, and ~.QuerySet.intersection raise DatabaseError when a field in .Options.ordering isn't selected by ~.QuerySet.values or ~.QuerySet.values_list. Call ~.QuerySet.order_by without arguments after combining to clear the default ordering.

• SQL SELECT aliases originating from .QuerySet.annotate calls as well as table and JOIN aliases are now systematically quoted to prevent special character collisions. Because quoted aliases are case-sensitive, raw SQL references to aliases mixing case, such as when using .RawSQL, might have to be adjusted to also make use of quoting.

• ~django.db.models.Model._is_pk_set now returns False for DatabaseDefault values on unsaved instances.

• fetch_mode=None is added to the signature of ~django.db.models.Model.from_db.

System checks

• The check management command now supplies all databases if not specified. Callers should be prepared for databases to be accessed.

Dropped support for PostgreSQL 14

Upstream support for PostgreSQL 14 ends in November 2026. Django 6.1 supports PostgreSQL 15 and higher.

Dropped support for MySQL < 8.4

Upstream support for MySQL 8.0 ends in April 2026, and MySQL 8.1-8.3 are short-term innovation releases. Django 6.1 supports MySQL 8.4 and higher.

Dropped support for MariaDB < 10.11

Upstream support for MariaDB 10.6 ends in July 2026, and MariaDB 10.7-10.10 are short-term maintenance releases. Django 6.1 supports MariaDB 10.11 and higher.

Miscellaneous

• The minimum supported version of SQLite is increased from 3.31.0 to 3.37.0.

• The default value of the transitional setting SIGNED_COOKIE_LEGACY_SALT_FALLBACK is now False.

• In cases where cached pages or template fragments varied on arguments, e.g. vary headers for ~django.views.decorators.cache.cache_page and ~django.middleware.cache.UpdateCacheMiddleware, or the vary_on arguments to the cache template tag (generated by ~django.core.cache.utils.make_template_fragment_key), the cache keys are different from the keys generated by older versions of Django. After upgrading to Django 6.1, the first request to any previously cached page or template fragment that varies on additional information will be a cache miss.

• ~django.contrib.contenttypes.fields.GenericForeignKey now uses a separate descriptor class: the private GenericForeignKeyDescriptor.

• The undocumented django.template.library.parse_bits() function no longer accepts the takes_context argument.

• The ~django.core.files.File class now always evaluates to True in boolean contexts, rather than relying on the name attribute. The built-in subclasses FieldFile, UploadedFile, TemporaryUploadedFile, InMemoryUploadedFile, and SimpleUploadedFile retain the previous behavior of evaluating based on the name attribute.

• The undocumented connection() method of .log.AdminEmailHandler has been removed and is no longer called. Subclasses overriding .AdminEmailHandler.send_mail should avoid calling connection(). See migrating-to-mailers-get-connection if specific connection configuration is needed.

• The internal implementation of .BrokenLinkEmailsMiddleware has been updated for mailers. If you have subclassed it to customize email sending behavior (as suggested in /howto/error-reporting), you may want to review the updates in the base .BrokenLinkEmailsMiddleware class.

• django.http.multipartparser.MultiPartParser now uses strict Base64 validation when decoding encoded request data. Previously, invalid data could be silently ignored or result in empty values. Invalid data now raises MultiPartParserError.

• django.core.cache.backends.db.DatabaseCache now uses strict Base64 validation when decoding cached values. Invalid Base64 data will raise an exception instead of being silently ignored. Cache values generated by Django are unaffected, as they are always valid Base64. However, existing cache entries containing non-standard or corrupted Base64 data may no longer be readable.

Features deprecated in 6.1

Email

• The EMAIL_BACKEND, EMAIL_FILE_PATH, EMAIL_HOST, EMAIL_HOST_PASSWORD, EMAIL_HOST_USER, EMAIL_PORT, EMAIL_USE_TLS, EMAIL_USE_SSL, EMAIL_SSL_CERTFILE, EMAIL_SSL_KEYFILE, and EMAIL_TIMEOUT settings are deprecated. Replace them with a MAILERS configuration dictionary as described in migrating-to-mailers.

• .mail.get_connection is deprecated. See migrating-to-mailers-get-connection for replacement options.

• The connection argument to .send_mail, .send_mass_mail, .mail_admins, .mail_managers, and .EmailMessage is deprecated. The EmailMessage.connection attribute is also deprecated. Switch to the using argument with a MAILERS alias.

• The fail_silently argument to .send_mail, .send_mass_mail, .mail_admins, .mail_managers, and .EmailMessage.send is deprecated. See migrating-to-mailers-fail-silently for alternatives.

• The auth_user and auth_password arguments to .send_mail and .send_mass_mail are deprecated. Replace them with "username" and "password" OPTIONS in MAILERS. See migrating-to-mailers-auth.

• Directly constructing and using instances of the smtp.EmailBackend class is deprecated. Use .mail.mailers to obtain email backend instances.

• The BaseEmailBackend.__init__() constructor no longer silently ignores unknown keyword arguments. Custom email backend subclasses should ensure they have consumed all supported **kwargs before forwarding the remainder to superclass init. The base class now issues a deprecation warning for unknown arguments, and it will treat them as errors starting in Django 2028. See migrating-to-mailers-email-backends.

• Support for fail_silently in the BaseEmailBackend is deprecated. A custom email backend that wants to support fail_silently should manage its own local attribute, not pass it to the base backend constructor. See migrating-to-mailers-email-backends.

Miscellaneous

• Calling ~django.db.models.query.QuerySet.select_related with no arguments to select all non-nullable related fields is deprecated. Specify the related fields to fetch instead, or use the ~django.db.models.FETCH_PEERS fetch mode.

• Setting .ModelAdmin.list_select_related to True and returning True from .ModelAdmin.get_list_select_related() are deprecated. Specify the related fields to fetch instead.

• Calling .QuerySet.values_list with flat=True and no field name is deprecated. Pass an explicit field name, like values_list("pk", flat=True).

• Support for Model.from_db() methods that do not accept the fetch_mode keyword argument is deprecated.

• The use of None to represent a top-level JSON scalar null when querying ~django.db.models.JSONField is now deprecated in favor of the new ~django.db.models.JSONNull expression. At the end of the deprecation period, None values compile to SQL IS NULL when used as the top-level value. Key and index lookups are unaffected by this deprecation.

• The undocumented django.db.models.fields.BLANK_CHOICE_DASH constant is deprecated. See the USE_BLANK_CHOICE_DASH transitional setting for migration advice.

• The USE_BLANK_CHOICE_DASH transitional setting is deprecated.

• The SIGNED_COOKIE_LEGACY_SALT_FALLBACK transitional setting is deprecated.

• The undocumented get_placeholder method of ~django.db.models.Field is deprecated in favor of the newly introduced get_placeholder_sql method, which has the same input signature but is expected to return a two-elements tuple composed of an SQL format string and a tuple of associated parameters. This method should now expect to be provided expressions meant to be compiled via the provided compiler argument.

• The quote_name_unless_alias() method of SQLCompiler, the type of object passed as the compiler argument to the as_sql() method of expressions, is deprecated in favor of the newly introduced quote_name() method.

• The email_backend argument of .log.AdminEmailHandler is deprecated in favor of the newly introduced using argument. See migrating-to-mailers-adminemailhandler for details.

• The BitAnd, BitOr, and BitXor classes in django.contrib.postgres.aggregates are deprecated in favor of the generally available ~django.db.models.BitAnd, ~django.db.models.BitOr, and ~django.db.models.BitXor classes.

• Support for double-dot variable lookups, like {{ book..title }}, is deprecated. This syntax maps to a lookup of the empty string, which is normally a mistake.

• The default value of the algorithm argument for django.utils.crypto.salted_hmac() and django.core.signing.base64_hmac() is deprecated and will change from "sha1" to "sha256" in Django 2028. Pass an explicit algorithm to silence the deprecation warning.

• Overriding ModelAdmin.get_actions() without the new action_location parameter is deprecated.

• Unpacking or indexing the dictionary values of the ModelAdmin.get_actions() return value is deprecated. Use ~django.contrib.admin.Action attributes instead.

• Overriding ModelAdmin.get_action_choices() without the new action_location parameter is deprecated.

• django.db.transaction.savepoint is deprecated in favor of ~django.db.transaction.savepoint_create.

Features removed in 6.1

These features have reached the end of their deprecation cycle and are removed in Django 6.1.

See deprecated-features-5.2 for details on these changes, including how to remove usage of these features.

• The all parameter for the django.contrib.staticfiles.finders.find() function is removed in favor of the find_all parameter.

• Fallbacks to request.user and request.auser() when user is None in django.contrib.auth.login() and django.contrib.auth.alogin(), respectively, are removed.

• The ordering keyword parameter of the PostgreSQL specific aggregation functions django.contrib.postgres.aggregates.ArrayAgg, django.contrib.postgres.aggregates.JSONBAgg, and django.contrib.postgres.aggregates.StringAgg are removed in favor of the order_by parameter.

• Support for subclasses of RemoteUserMiddleware that override process_request() without overriding aprocess_request() is removed.

Django 6.0 release notes

December 3, 2025

Welcome to Django 6.0!

These release notes cover the new features, as well as some backwards incompatible changes you should be aware of when upgrading from Django 5.2 or earlier. We've begun the deprecation process for some features.

See the /howto/upgrade-version guide if you're updating an existing project.

Python compatibility

Django 6.0 supports Python 3.12, 3.13, and 3.14. We highly recommend, and only officially support, the latest release of each series.

The Django 5.2.x series is the last to support Python 3.10 and 3.11.

Third-party library support for older versions of Django

Following the release of Django 6.0, we suggest that third-party app authors drop support for all versions of Django prior to 5.2. At that time, you should be able to run your package's tests using python -Wd so that deprecation warnings appear. After making the deprecation warning fixes, your app should be compatible with Django 6.0.

What's new in Django 6.0

Content Security Policy support

Built-in support for the Content Security Policy (CSP) standard is now available, making it easier to protect web applications against content injection attacks such as cross-site scripting (XSS). CSP allows declaring trusted sources of content by giving browsers strict rules about which scripts, styles, images, or other resources can be loaded.

CSP policies can now be enforced or monitored directly using built-in tools: headers are added via the ~django.middleware.csp.ContentSecurityPolicyMiddleware, nonces are supported through the ~django.template.context_processors.csp context processor, and policies are configured using the SECURE_CSP and SECURE_CSP_REPORT_ONLY settings.

These settings accept Python dictionaries and support Django-provided constants for clarity and safety. For example:

from django.utils.csp import CSP

SECURE_CSP = {
    "default-src": [CSP.SELF],
    "script-src": [CSP.SELF, CSP.NONCE],
    "img-src": [CSP.SELF, "https:"],
}

The resulting Content-Security-Policy header would be set to:

default-src 'self'; script-src 'self' 'nonce-SECRET'; img-src 'self' https:

To get started, follow the CSP how-to guide. For in-depth guidance, see the CSP security overview and the reference docs, which include details about decorators to override or disable policies on a per-view basis.

Template Partials

The Django Template Language now supports template partials, making it easier to encapsulate and reuse small named fragments within a template file. The new tags {% partialdef %} and {% partial %} define a partial and render it, respectively.

Partials can also be referenced using the template_name#partial_name syntax with ~django.template.Engine.get_template, ~django.shortcuts.render, {% include %}, and other template-loading tools, enabling more modular and maintainable templates without needing to split components into separate files.

A migration guide is available if you're updating from the django-template-partials third-party package.

Background Tasks

Django now includes a built-in Tasks framework for running code outside the HTTP request–response cycle. This enables offloading work, such as sending emails or processing data, to background workers.

The framework provides task definition, validation, queuing, and result handling. Django guarantees consistent behavior for creating and managing tasks, while the responsibility for running them continues to belong to external worker processes.

Tasks are defined using the ~django.tasks.task decorator:

from django.core.mail import send_mail
from django.tasks import task


@task
def email_users(emails, subject, message):
    return send_mail(subject, message, None, emails)

Once defined, tasks can be enqueued through a configured backend:

email_users.enqueue(
    emails=["user@example.com"],
    subject="You have a message",
    message="Hello there!",
)

Backends are configured via the TASKS setting. The two built-in backends included in this release are primarily intended for development and testing.

Django handles task creation and queuing, but does not provide a worker mechanism to run tasks. Execution must be managed by external infrastructure, such as a separate process or service.

See /topics/tasks for an overview and the Tasks reference for API details.

Adoption of Python's modern email API

Email handling in Django now uses Python's modern email API, introduced in Python 3.6. This API, centered around the email.message.EmailMessage class, offers a cleaner and Unicode-friendly interface for composing and sending emails. It replaces use of Python's older legacy (Compat32) API, which relied on lower-level MIME classes (from email.mime) and required more manual handling of message structure and encoding.

Notably, the return type of the EmailMessage.message() method is now an instance of Python's email.message.EmailMessage. This supports the same API as the previous SafeMIMEText and SafeMIMEMultipart return types, but is not an instance of those now-deprecated classes.

Minor features

django.contrib.admin

• The Font Awesome Free icon set (version 6.7.2) is now used for the admin interface icons.

• The new .AdminSite.password_change_form attribute allows customizing the form used in the admin site password change view.

• Message levels messages.DEBUG and messages.INFO now have distinct icons and CSS styling. Previously, both levels shared the same appearance as messages.SUCCESS. Given that .ModelAdmin.message_user uses messages.INFO by default, set the level to messages.SUCCESS to keep the previous icon and styling.

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 1,000,000 to 1,200,000.

django.contrib.gis

• The new .GEOSGeometry.hasm property checks whether the geometry has the M dimension.

• The new ~django.contrib.gis.db.models.functions.Rotate database function rotates a geometry by a specified angle around the origin or a specified point.

• The new .BaseGeometryWidget.base_layer attribute allows specifying a JavaScript map base layer, enabling customization of map tile providers.

• coveredby and isvalid lookups, ~django.contrib.gis.db.models.Collect aggregation, and ~django.contrib.gis.db.models.functions.GeoHash and ~django.contrib.gis.db.models.functions.IsValid database functions are now supported on MariaDB 12.0.1+.

• The new geom_type lookup and GeometryType() database function allow filtering geometries by their types.

• Widgets from django.contrib.gis.forms.widgets now render without inline JavaScript in templates. If you have customized any geometry widgets or their templates, you may need to update them to match the new layout.

django.contrib.postgres

• The new Lexeme expression for full text search provides fine-grained control over search terms. Lexeme objects automatically escape their input and support logical combination operators (&, |, ~), prefix matching, and term weighting.

• Model fields, indexes, and constraints from django.contrib.postgres now include system checks to verify that django.contrib.postgres is an installed app.

• The .CreateExtension, .BloomExtension, .BtreeGinExtension, .BtreeGistExtension, .CITextExtension, .CryptoExtension, .HStoreExtension, .TrigramExtension, and .UnaccentExtension operations now support the optional hints parameter. This allows providing database hints to database routers to assist them in making routing decisions.

django.contrib.staticfiles

• ~django.contrib.staticfiles.storage.ManifestStaticFilesStorage now ensures consistent path ordering in manifest files, making them more reproducible and reducing unnecessary diffs.

• The collectstatic command now reports only a summary for skipped files (and for deleted files when using --clear) at --verbosity 1. To see per-file details for either case, set --verbosity to 2 or higher.

Email

• The new policy argument for EmailMessage.message() allows specifying the email policy, the set of rules for updating and serializing the representation of the message. Defaults to email.policy.default.

• EmailMessage.attach() now accepts a ~email.message.MIMEPart object from Python's modern email API.

Internationalization

• Added support and translations for the Haitian Creole language.

Management Commands

• The startproject and startapp commands now create the custom target directory if it doesn't exist.

• Common utilities, such as django.conf.settings, are now automatically imported to the shell by default.

Migrations

• Squashed migrations can now themselves be squashed before being transitioned to normal migrations.

• Migrations now support serialization of zoneinfo.ZoneInfo instances.

• Serialization of deconstructible objects now supports keyword arguments with names that are not valid Python identifiers.

Models

• Constraints now implement a check() method that is already registered with the check framework.

• The new order_by argument for ~django.db.models.Aggregate allows specifying the ordering of the elements in the result.

• The new .Aggregate.allow_order_by class attribute determines whether the aggregate function allows passing an order_by keyword argument.

• The new ~django.db.models.StringAgg aggregate returns the input values concatenated into a string, separated by the delimiter string. This aggregate was previously supported only for PostgreSQL.

• The ~django.db.models.Model.save method now raises a specialized Model.NotUpdated exception, when a forced update results in no affected rows, instead of a generic django.db.DatabaseError.

• .QuerySet.raw now supports models with a ~django.db.models.CompositePrimaryKey.

• Subqueries returning a ~django.db.models.CompositePrimaryKey can now be used as the target of lookups other than __in, such as __exact.

• ~django.db.models.JSONField now supports negative array indexing on SQLite.

• The new ~django.db.models.AnyValue aggregate returns an arbitrary value from the non-null input values. This is supported on SQLite, MySQL, Oracle, and PostgreSQL 16+.

• ~django.db.models.GeneratedFields and fields assigned expressions are now refreshed from the database after ~django.db.models.Model.save on backends that support the RETURNING clause (SQLite, PostgreSQL, and Oracle). On backends that don't support it (MySQL and MariaDB), the fields are marked as deferred to trigger a refresh on subsequent accesses.

• Using a ForeignObject with multiple from_fields in Model indexes, constraints, or unique_together now emits a system check error.

Pagination

• The new ~django.core.paginator.AsyncPaginator and ~django.core.paginator.AsyncPage provide async implementations of ~django.core.paginator.Paginator and ~django.core.paginator.Page respectively.

Requests and Responses

• Multiple Cookie headers are now supported for HTTP/2 requests when running with ASGI.

Templates

• The new variable forloop.length is now available within a for loop.

• The querystring template tag now consistently prefixes the returned query string with a ?, ensuring reliable link generation behavior.

• The querystring template tag now accepts multiple positional arguments, which must be mappings, such as ~django.http.QueryDict or dict.

Tests

• The .DiscoverRunner now supports parallel test execution on systems using the forkserver multiprocessing start method.

Backwards incompatible changes in 6.0

Database backend API

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

• ~django.db.backends.base.schema.BaseDatabaseSchemaEditor and PostgreSQL backends no longer use CASCADE when dropping a column.

• DatabaseOperations.return_insert_columns() and DatabaseOperations.fetch_returned_insert_rows() methods are renamed to returning_columns() and fetch_returned_rows(), respectively, to denote they can be used in the context of UPDATE … RETURNING statements as well as INSERT … RETURNING.

• The DatabaseOperations.fetch_returned_insert_columns() method is removed and the fetch_returned_rows() method replacing fetch_returned_insert_rows() expects both a cursor and returning_params to be provided, just like fetch_returned_insert_columns() did.

• If the database supports UPDATE … RETURNING statements, backends can set DatabaseFeatures.can_return_rows_from_update=True.

Dropped support for MariaDB 10.5

Upstream support for MariaDB 10.5 ends in June 2025. Django 6.0 supports MariaDB 10.6 and higher.

Dropped support for Python < 3.12

Because Python 3.12 is now the minimum supported version for Django, any optional dependencies must also meet that requirement. The following versions of each library are the first to add or confirm compatibility with Python 3.12:

• aiosmtpd 1.4.5

• argon2-cffi 23.1.0

• bcrypt 4.1.1

• docutils 0.22

• geoip2 4.8.0

• Pillow 10.1.0

• mysqlclient 2.2.1

• numpy 1.26.0

• PyYAML 6.0.2

• psycopg 3.1.12

• psycopg2 2.9.9

• redis-py 5.1.0

• selenium 4.23.0

• sqlparse 0.5.0

• tblib 3.0.0

Email

• The undocumented mixed_subtype and alternative_subtype properties of ~django.core.mail.EmailMessage and ~django.core.mail.EmailMultiAlternatives are no longer supported.

• The undocumented encoding property of ~django.core.mail.EmailMessage no longer supports Python legacy email.charset.Charset objects.

• As the internal implementations of ~django.core.mail.EmailMessage and ~django.core.mail.EmailMultiAlternatives have changed significantly, closely examine any custom subclasses that rely on overriding undocumented, internal underscore methods.

DEFAULT_AUTO_FIELD setting now defaults to BigAutoField

Since Django 3.2, when the DEFAULT_AUTO_FIELD setting was added, the default startproject template's settings.py contained:

DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

and the default startapp template's AppConfig contained:

default_auto_field = "django.db.models.BigAutoField"

At that time, the default value of DEFAULT_AUTO_FIELD remained django.db.models.AutoField for backwards compatibility.

In Django 6.0, DEFAULT_AUTO_FIELD now defaults to django.db.models.BigAutoField and the aforementioned lines in the project and app templates are removed.

Most projects shouldn't be affected, since Django 3.2 has raised the system check warning models.W042 for projects that don't set DEFAULT_AUTO_FIELD.

If you haven't dealt with this warning by now, add DEFAULT_AUTO_FIELD = 'django.db.models.AutoField' to your project's settings, or default_auto_field = 'django.db.models.AutoField' to an app's AppConfig, as needed.

Custom ORM expressions should return params as a tuple

Prior to Django 6.0, custom lookups and custom expressions implementing the as_sql() method (and its supporting methods process_lhs() and process_rhs()) were allowed to return a sequence of params in either a list or a tuple. To address the interoperability problems that resulted, the second return element of the as_sql() method should now be a tuple:

def as_sql(self, compiler, connection) -> tuple[str, tuple]: ...

If your custom expressions support multiple versions of Django, you should adjust any pre-processing of parameters to be resilient against either tuples or lists. For instance, prefer unpacking like this:

params = (*lhs_params, *rhs_params)

Miscellaneous

• The JSON serializer now writes a newline at the end of the output, even without the indent option set.

• The minimum supported version of asgiref is increased from 3.8.1 to 3.9.1.

• Field.pre_save may now be called more than once when saving model instances, so custom implementations should be idempotent and free of side effects.

Features deprecated in 6.0

Positional arguments in django.core.mail APIs

django.core.mail APIs now require keyword arguments for less commonly used parameters. Using positional arguments for these now emits a deprecation warning and will raise a TypeError when the deprecation period ends:

• All optional parameters (fail_silently and later) must be passed as keyword arguments to .get_connection, .mail_admins, .mail_managers, .send_mail, and .send_mass_mail.

• All parameters must be passed as keyword arguments when creating an .EmailMessage or .EmailMultiAlternatives instance, except for the first four (subject, body, from_email, and to), which may still be passed either as positional or keyword arguments.

Miscellaneous

• BaseDatabaseCreation.create_test_db(serialize) is deprecated. Use serialize_db_to_string() instead.

• The PostgreSQL StringAgg class is deprecated in favor of the generally available ~django.db.models.StringAgg class.

• Passing a string to the ~django.contrib.postgres.aggregates.StringAgg.delimiter argument of the (deprecated) PostgreSQL StringAgg class is deprecated. Use a ~django.db.models.Value or expression instead to prepare for compatibility with the generally available ~django.db.models.StringAgg class.

• The PostgreSQL OrderableAggMixin is deprecated in favor of the order_by attribute now available on the ~django.db.models.Aggregate class.

• The default protocol in urlize and urlizetrunc will change from HTTP to HTTPS in Django 2028. Set the transitional setting URLIZE_ASSUME_HTTPS to True to opt into assuming HTTPS during the Django 6.x release cycle.

• The URLIZE_ASSUME_HTTPS transitional setting is deprecated.

• Setting ADMINS or MANAGERS to a list of (name, address) tuples is deprecated. Set to a list of email address strings instead. Django never used the name portion. To include a name, format the address string as '"Name" <address>' or use Python's email.utils.formataddr.

• Support for the orphans argument being larger than or equal to the per_page argument of django.core.paginator.Paginator and django.core.paginator.AsyncPaginator is deprecated.

• Using a percent sign in a column alias or annotation is deprecated.

• Support for passing Python's legacy email ~email.mime.base.MIMEBase object to EmailMessage.attach() (or including one in the message's attachments list) is deprecated. For complex attachments requiring additional headers or parameters, switch to the modern email API's ~email.message.MIMEPart.

• The django.core.mail.BadHeaderError exception is deprecated. Python's modern email raises a !ValueError for email headers containing prohibited characters.

• The django.core.mail.SafeMIMEText and SafeMIMEMultipart classes are deprecated.

• The undocumented django.core.mail.forbid_multi_line_headers() and django.core.mail.message.sanitize_address() functions are deprecated.

Features removed in 6.0

These features have reached the end of their deprecation cycle and are removed in Django 6.0.

See deprecated-features-5.0 for details on these changes, including how to remove usage of these features.

• Support for passing positional arguments to BaseConstraint is removed.

• The DjangoDivFormRenderer and Jinja2DivFormRenderer transitional form renderers are removed.

• BaseDatabaseOperations.field_cast_sql() is removed.

• request is required in the signature of ModelAdmin.lookup_allowed() subclasses.

• Support for calling format_html() without passing args or kwargs is removed.

• The default scheme for forms.URLField has changed from "http" to "https".

• The FORMS_URLFIELD_ASSUME_HTTPS transitional setting is removed.

• The django.db.models.sql.datastructures.Join no longer falls back to get_joining_columns().

• The get_joining_columns() method of ForeignObject and ForeignObjectRel is removed.

• The ForeignObject.get_reverse_joining_columns() method is removed.

• Support for cx_Oracle is removed.

• The ChoicesMeta alias to django.db.models.enums.ChoicesType is removed.

• The Prefetch.get_current_queryset() method is removed.

• The get_prefetch_queryset() method of related managers and descriptors is removed.

• get_prefetcher() and prefetch_related_objects() no longer fall back to get_prefetch_queryset().

See deprecated-features-5.1 for details on these changes, including how to remove usage of these features.

• django.urls.register_converter() no longer allows overriding existing converters.

• The ModelAdmin.log_deletion() and LogEntryManager.log_action() methods are removed.

• The undocumented django.utils.itercompat.is_iterable() function and the django.utils.itercompat module are removed.

• The django.contrib.gis.geoip2.GeoIP2.coords() method is removed.

• The django.contrib.gis.geoip2.GeoIP2.open() method is removed.

• Support for passing positional arguments to Model.save() and Model.asave() is removed.

• The setter for django.contrib.gis.gdal.OGRGeometry.coord_dim is removed.

• The check keyword argument of CheckConstraint is removed.

• The get_cache_name() method of FieldCacheMixin is removed.

• The OS_OPEN_FLAGS attribute of ~django.core.files.storage.FileSystemStorage is removed.

Django 5.2 release notes

April 2, 2025

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 Django 5.1 or earlier. We've begun the deprecation process for some features.

See the /howto/upgrade-version guide if you're updating an existing project.

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

Python compatibility

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

What's new in Django 5.2

Automatic models import in the shell

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

This behavior can be customized to add or remove automatic imports.

Composite Primary Keys

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

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

from django.db import models


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

See /topics/composite-primary-key for more details.

Simplified override of ~django.forms.BoundField

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

• .BaseRenderer.bound_field_class at the project level,

• .Form.bound_field_class at the form level, and

• .Field.bound_field_class at the field level.

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

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")

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

<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>

See custom-boundfield for more details about this feature.

Minor features

django.contrib.admin

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

• The value of a ~django.db.models.URLField now renders as a link.

django.contrib.admindocs

• Links to components in docstrings now supports custom link text, using the format link text. See documentation helpers for more details.

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

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 870,000 to 1,000,000.

• The following new asynchronous methods are now provided, using an a prefix:

  • .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

• Auth backends can now provide async implementations which are used when calling async auth functions (e.g. ~.django.contrib.auth.aauthenticate) to reduce context-switching which improves performance. See adding an async interface for more details.

• The password validator classes now have a new method get_error_message(), which can be overridden in subclasses to customize the error messages.

django.contrib.gis

• GDAL now supports curved geometries CurvePolygon, CompoundCurve, CircularString, MultiSurface, and MultiCurve via the new .OGRGeometry.has_curve property, and the .OGRGeometry.get_linear_geometry and .OGRGeometry.get_curve_geometry methods.

• coveredby and covers lookup are now supported on MySQL.

django.contrib.syndication

• All ~django.utils.feedgenerator.SyndicationFeed classes now support a stylesheets attribute. If specified, an <? xml-stylesheet ?> processing instruction will be added to the top of the document for each stylesheet in the given list. See feed-stylesheets for more details.

Database backends

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

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

Decorators

• ~django.utils.decorators.method_decorator now supports wrapping asynchronous view methods.

Email

• Tuple items of EmailMessage.attachments and EmailMultiAlternatives.attachments are now named tuples, as opposed to regular tuples.

• EmailMultiAlternatives.alternatives is now a list of named tuples, as opposed to regular tuples.

• The new ~django.core.mail.EmailMultiAlternatives.body_contains method returns a boolean indicating whether a provided text is contained in the email body and in all attached MIME type text/* alternatives.

Error Reporting

• The attribute .SafeExceptionReporterFilter.hidden_settings now treats values as sensitive if their name includes AUTH.

Forms

• The new ~django.forms.ColorInput form widget is for entering a color in rrggbb hexadecimal format and renders as <input type="color" ...>. Some browsers support a visual color picker interface for this input type.

• The new ~django.forms.SearchInput form widget is for entering search queries and renders as <input type="search" ...>.

• The new ~django.forms.TelInput form widget is for entering telephone numbers and renders as <input type="tel" ...>.

• The new field_id argument for ~django.forms.ErrorList allows an HTML id attribute to be added in the error template. See .ErrorList.field_id for details.

• An ~django.forms.BoundField.aria_describedby property is added to BoundField to ease use of this HTML attribute in templates.

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

• The new asset object ~django.forms.Script is available for adding custom HTML-attributes to JavaScript in form media. See paths as objects for more details.

Management Commands

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

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

• The new .BaseCommand.get_check_kwargs method can be overridden in custom commands to control the running of system checks, e.g. to opt into database-dependent checks.

Migrations

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

Models

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

• Added support for validation of model constraints which use a ~django.db.models.GeneratedField.

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

• CharField.max_length is no longer required to be set on SQLite, which supports unlimited VARCHAR columns.

• .QuerySet.explain now supports the memory and serialize options on PostgreSQL 17+.

• The new ~django.db.models.functions.JSONArray database function accepts a list of field names or expressions and returns a JSON array containing those values.

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

Requests and Responses

• The new .HttpResponse.text property provides the string representation of .HttpResponse.content.

• The new .HttpRequest.get_preferred_type method can be used to query the preferred media type the client accepts.

• The new preserve_request argument for ~django.http.HttpResponseRedirect and ~django.http.HttpResponsePermanentRedirect determines whether the HTTP status codes 302/307 or 301/308 are used, respectively.

• The new preserve_request argument for ~django.shortcuts.redirect allows to instruct the user agent to reuse the HTTP method and body during redirection using specific status codes.

Serialization

• Each serialization format now defines a Deserializer class, rather than a function, to improve extensibility when defining a custom serialization format.

Templates

• The new ~django.template.Library.simple_block_tag decorator enables the creation of simple block tags, which can accept and use a section of the template.

Tests

• Stack frames from Django's custom assertions are now hidden. This makes test failures easier to read and enables test --pdb to directly enter into the failing test method.

• Data loaded from ~django.test.TransactionTestCase.fixtures and from migrations enabled with serialized_rollback=True are now available during TransactionTestCase.setUpClass().

URLs

• ~django.urls.reverse and ~django.urls.reverse_lazy now accept query and fragment keyword arguments, allowing the addition of a query string and/or fragment identifier in the generated URL, respectively.

Utilities

• ~django.utils.safestring.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.

• ~django.utils.html.format_html_join now supports taking an iterable of mappings, passing their contents as keyword arguments to ~django.utils.html.format_html.

Backwards incompatible changes in 5.2

Database backend API

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

• The new Model._is_pk_set() method allows checking if a Model instance's primary key is defined.

• BaseDatabaseOperations.adapt_decimalfield_value() is now a no-op, simply returning the given value.

django.contrib.gis

• Support for PostGIS 3.0 is removed.

• Support for GDAL 3.0 is removed.

Dropped support for PostgreSQL 13

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

Changed MySQL connection character set default

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

Miscellaneous

• Adding .EmailMultiAlternatives.alternatives is now only supported via the ~.EmailMultiAlternatives.attach_alternative method.

• The minimum supported version of gettext is increased from 0.15 to 0.19.

• HttpRequest.accepted_types is now sorted by the client's preference, based on the request's Accept header.

• The attributes .UniqueConstraint.violation_error_code and .UniqueConstraint.violation_error_message are now always used when provided. Previously, they were ignored if .UniqueConstraint.fields was set without a .UniqueConstraint.condition.

• The ~django.template.context_processors.debug context processor is no longer included in the default project template.

• The following methods now have alters_data=True set to prevent side effects when rendering a template context:

  • .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

• The minimum supported version of oracledb is increased from 1.3.2 to 2.3.0.

• Built-in aggregate functions accepting only one argument (Avg, Count, Max, Min, StdDev, Sum, and Variance) now raise TypeError when called with an incorrect number of arguments.

Features deprecated in 5.2

Miscellaneous

• The all argument for the django.contrib.staticfiles.finders.find() function is deprecated in favor of the find_all argument.

• Fallbacks to request.user and request.auser() when user is None in django.contrib.auth.login() and django.contrib.auth.alogin(), respectively, are deprecated.

• The ordering keyword argument of the PostgreSQL specific aggregation functions django.contrib.postgres.aggregates.ArrayAgg, django.contrib.postgres.aggregates.JSONBAgg, and django.contrib.postgres.aggregates.StringAgg is deprecated in favor of the order_by argument.

• Support for subclasses of RemoteUserMiddleware that override process_request() without overriding aprocess_request() is deprecated.

Django 5.1 release notes

August 7, 2024

Welcome to Django 5.1!

These release notes cover the new features, as well as some backwards incompatible changes you should be aware of when upgrading from Django 5.0 or earlier. We've begun the deprecation process for some features.

See the /howto/upgrade-version guide if you're updating an existing project.

Python compatibility

Django 5.1 supports Python 3.10, 3.11, 3.12, and 3.13 (as of 5.1.3). We highly recommend and only officially support the latest release of each series.

What's new in Django 5.1

{% querystring %} template tag

Django 5.1 introduces the {% querystring %} template tag, simplifying the modification of query parameters in URLs, making it easier to generate links that maintain existing query parameters while adding or changing specific ones.

For instance, navigating pagination and query strings in templates can be cumbersome. Consider this template fragment that dynamically generates a URL for navigating to the next page within a paginated view:

{# Linebreaks added for readability, this should be one, long line. #}
<a href="?{% for key, values in request.GET.iterlists %}
  {% if key != "page" %}
    {% for value in values %}
      {{ key }}={{ value }}&amp;
    {% endfor %}
  {% endif %}
{% endfor %}page={{ page.next_page_number }}">Next page</a>

When switching to using this new template tag, the above magically becomes:

<a href="{% querystring page=page.next_page_number %}">Next page</a>

PostgreSQL Connection Pools

Django 5.1 also introduces connection pool support for PostgreSQL. As the time to establish a new connection can be relatively long, keeping connections open can reduce latency.

To use a connection pool with psycopg, you can set the "pool" option inside OPTIONS to be a dict to be passed to ~psycopg:psycopg_pool.ConnectionPool, or to True to use the ConnectionPool defaults:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        # ...
        "OPTIONS": {
            "pool": {
                "min_size": 2,
                "max_size": 4,
                "timeout": 10,
            }
        },
    },
}

Middleware to require authentication by default

The new ~django.contrib.auth.middleware.LoginRequiredMiddleware redirects all unauthenticated requests to a login page. Views can allow unauthenticated requests by using the new ~django.contrib.auth.decorators.login_not_required decorator.

LoginRequiredMiddleware respects the login_url and redirect_field_name values set via the ~.django.contrib.auth.decorators.login_required decorator, but does not support setting login_url or redirect_field_name via the ~django.contrib.auth.mixins.LoginRequiredMixin.

To enable this, add "django.contrib.auth.middleware.LoginRequiredMiddleware" to your MIDDLEWARE setting.

Minor features

django.contrib.admin

• .ModelAdmin.list_display now supports using __ lookups to list fields from related models.

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 720,000 to 870,000.

• The default parallelism of the ScryptPasswordHasher is increased from 1 to 5, to follow OWASP recommendations.

• The new ~django.contrib.auth.forms.AdminUserCreationForm and the existing ~django.contrib.auth.forms.AdminPasswordChangeForm now support disabling password-based authentication by setting an unusable password on form save. This is now available in the admin when visiting the user creation and password change pages.

• ~.django.contrib.auth.decorators.login_required, ~.django.contrib.auth.decorators.permission_required, and ~.django.contrib.auth.decorators.user_passes_test decorators now support wrapping asynchronous view functions.

• ReadOnlyPasswordHashWidget now includes a button to reset the user's password, which replaces the link previously embedded in the ReadOnlyPasswordHashField's help text, improving the overall accessibility of the ~django.contrib.auth.forms.UserChangeForm.

django.contrib.gis

• ~django.contrib.gis.db.models.functions.BoundingCircle is now supported on SpatiaLite 5.1+.

• ~django.contrib.gis.db.models.Collect is now supported on MySQL 8.0.24+.

• ~django.contrib.gis.geoip2.GeoIP2 now allows querying using ipaddress.IPv4Address or ipaddress.IPv6Address objects.

• .GeoIP2.country now exposes the continent_code, continent_name, and is_in_european_union values.

• .GeoIP2.city now exposes the accuracy_radius and region_name values. In addition, the dma_code and region values are now exposed as metro_code and region_code, but the previous keys are also retained for backward compatibility.

• ~django.contrib.gis.measure.Area now supports the ha unit.

• The new .OGRGeometry.is_3d attribute allows checking if a geometry has a Z coordinate dimension.

• The new .OGRGeometry.set_3d method allows addition and removal of the Z coordinate dimension.

• ~django.contrib.gis.gdal.OGRGeometry, ~django.contrib.gis.gdal.Point, ~django.contrib.gis.gdal.LineString, ~django.contrib.gis.gdal.Polygon, and ~django.contrib.gis.gdal.GeometryCollection and its subclasses now support measured geometries via the new .OGRGeometry.is_measured and m properties, and the .OGRGeometry.set_measured method.

• .OGRGeometry.centroid is now available on all supported geometry types.

• FromWKB() and FromWKT() functions now support the optional srid argument (except for Oracle where it is ignored).

django.contrib.postgres

• ~django.contrib.postgres.indexes.BTreeIndex now supports the deduplicate_items parameter.

django.contrib.sessions

• django.contrib.sessions.backends.cached_db.SessionStore now handles exceptions when storing session information in the cache, logging proper error messages with their traceback via the newly added sessions logger.

• django.contrib.sessions.backends.base.SessionBase and all built-in session engines now provide async API. The new asynchronous methods all have a prefixed names, e.g. aget(), akeys(), or acycle_key().

Database backends

• "init_command" option is now supported in OPTIONS on SQLite to allow specifying pragma options to set upon connection.

• "transaction_mode" option is now supported in OPTIONS on SQLite to allow specifying the sqlite-transaction-behavior.

• "pool" option is now supported in OPTIONS on PostgreSQL to allow using connection pools.

Error Reporting

• In order to improve accessibility, the technical 404 and 500 error pages now use HTML landmark elements for the header, footer, and main content areas.

File Storage

• The ~django.core.files.storage.FileSystemStorage.allow_overwrite parameter of ~django.core.files.storage.FileSystemStorage now allows saving new files over existing ones.

Forms

• In order to improve accessibility and enable screen readers to associate fieldsets with their help text, the form fieldset now includes the aria-describedby HTML attribute.

Management Commands

• The makemigrations command now displays meaningful symbols for each operation to highlight operation categories.

Migrations

• The new Operation.category attribute allows specifying an operation category used by the makemigrations to display a meaningful symbol for the operation.

Models

• .QuerySet.explain now supports the generic_plan option on PostgreSQL 16+.

• ~django.db.models.expressions.RowRange now accepts positive integers for the start argument and negative integers for the end argument.

• The new exclusion argument of ~django.db.models.expressions.RowRange and ~django.db.models.expressions.ValueRange allows excluding rows, groups, and ties from the window frames.

• .QuerySet.order_by now supports ordering by annotation transforms such as JSONObject keys and ArrayAgg indices.

• F() and OuterRef() expressions that output ~django.db.models.CharField, ~django.db.models.EmailField, ~django.db.models.SlugField, ~django.db.models.URLField, ~django.db.models.TextField, or ~django.contrib.postgres.fields.ArrayField can now be sliced.

• The new from_queryset argument of .Model.refresh_from_db and .Model.arefresh_from_db allows customizing the queryset used to reload a model's value. This can be used to lock the row before reloading or to select related objects.

• The new .Expression.constraint_validation_compatible attribute allows specifying that the expression should be ignored during a constraint validation.

Templates

• Custom tags may now set extra data on the Parser object that will later be made available on the Template instance. Such data may be used, for example, by the template loader, or other template clients.

• Template engines now implement a check() method that is already registered with the check framework.

Tests

• ~django.test.SimpleTestCase.assertContains, ~django.test.SimpleTestCase.assertNotContains, and ~django.test.SimpleTestCase.assertInHTML assertions now add haystacks to assertion error messages.

• The ~django.test.RequestFactory, ~django.test.AsyncRequestFactory, ~django.test.Client, and ~django.test.AsyncClient classes now support the query_params parameter, which accepts a dictionary of query string keys and values. This allows setting query strings on any HTTP methods more easily.

  self.client.post("/items/1", query_params={"action": "delete"})
  await self.async_client.post("/items/1", query_params={"action": "delete"})

• The new .SimpleTestCase.assertNotInHTML assertion allows testing that an HTML fragment is not contained in the given HTML haystack.

• In order to enforce test isolation, database connections inside threads are no longer allowed in ~django.test.SimpleTestCase.

Validators

• The new ~django.core.validators.DomainNameValidator validates domain names, including internationalized domain names. The new ~django.core.validators.validate_domain_name function returns an instance of ~django.core.validators.DomainNameValidator.

Backwards incompatible changes in 5.1

django.contrib.gis

• Support for PostGIS 2.5 is removed.

• Support for PROJ < 6 is removed.

• Support for GDAL 2.4 is removed.

• ~django.contrib.gis.geoip2.GeoIP2 no longer opens both city and country databases when a directory path is provided, preferring the city database, if it is available. The country database is a subset of the city database and both are not typically needed. If you require use of the country database when in the same directory as the city database, explicitly pass the country database path to the constructor.

Dropped support for MariaDB 10.4

Upstream support for MariaDB 10.4 ends in June 2024. Django 5.1 supports MariaDB 10.5 and higher.

Dropped support for PostgreSQL 12

Upstream support for PostgreSQL 12 ends in November 2024. Django 5.1 supports PostgreSQL 13 and higher.

Miscellaneous

• In order to improve accessibility, the admin's changelist filter is now rendered in a <nav> tag instead of a <div>.

• In order to improve accessibility, the admin's footer is now rendered in a <footer> tag instead of a <div>, and also moved below the <div id="main"> element.

• In order to improve accessibility, the expandable widget used for ModelAdmin.fieldsets and InlineModelAdmin.fieldsets, when the fieldset has a name and use the collapse class, now includes <details> and <summary> elements.

• The JavaScript file collapse.js is removed since it is no longer needed in the Django admin site.

• .SimpleTestCase.assertURLEqual and ~django.test.SimpleTestCase.assertInHTML now add ": " to the msg_prefix. This is consistent with the behavior of other assertions.

• django.utils.text.Truncator used by truncatechars_html and truncatewords_html template filters now uses html.parser.HTMLParser subclasses. This results in a more robust and faster operation, but there may be small differences in the output.

• The undocumented django.urls.converters.get_converter() function is removed.

• The minimum supported version of SQLite is increased from 3.27.0 to 3.31.0.

• ~django.db.models.FileField now raises a ~django.core.exceptions.FieldError when saving a file without a name.

• ImageField.update_dimension_fields(force=True) is no longer called after saving the image to storage. If your storage backend resizes images, the width_field and height_field will not match the width and height of the image.

• The minimum supported version of asgiref is increased from 3.7.0 to 3.8.1.

• To improve performance, the delete_selected admin action now uses QuerySet.bulk_create() when creating multiple LogEntry objects. As a result, pre_save and post_save signals for LogEntry are not sent when multiple objects are deleted via this admin action.

Features deprecated in 5.1

Miscellaneous

• The ModelAdmin.log_deletion() and LogEntryManager.log_action() methods are deprecated. Subclasses should implement ModelAdmin.log_deletions() and LogEntryManager.log_actions() instead.

• The undocumented django.utils.itercompat.is_iterable() function and the django.utils.itercompat module are deprecated. Use isinstance(..., collections.abc.Iterable) instead.

• The django.contrib.gis.geoip2.GeoIP2.coords() method is deprecated. Use django.contrib.gis.geoip2.GeoIP2.lon_lat() instead.

• The django.contrib.gis.geoip2.GeoIP2.open() method is deprecated. Use the ~django.contrib.gis.geoip2.GeoIP2 constructor instead.

• Passing positional arguments to .Model.save and .Model.asave is deprecated in favor of keyword-only arguments.

• Setting django.contrib.gis.gdal.OGRGeometry.coord_dim is deprecated. Use ~django.contrib.gis.gdal.OGRGeometry.set_3d instead.

• Overriding existing converters with django.urls.register_converter() is deprecated.

• The check keyword argument of CheckConstraint is deprecated in favor of condition.

• The undocumented OS_OPEN_FLAGS property of ~django.core.files.storage.FileSystemStorage is deprecated. To allow overwriting files in storage, set the new ~django.core.files.storage.FileSystemStorage.allow_overwrite option to True instead.

• The get_cache_name() method of FieldCacheMixin is deprecated in favor of the cache_name cached property.

Features removed in 5.1

These features have reached the end of their deprecation cycle and are removed in Django 5.1.

See deprecated-features-4.2 for details on these changes, including how to remove usage of these features.

• The BaseUserManager.make_random_password() method is removed.

• The model's Meta.index_together option is removed.

• The length_is template filter is removed.

• The django.contrib.auth.hashers.SHA1PasswordHasher, django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher, and django.contrib.auth.hashers.UnsaltedMD5PasswordHasher are removed.

• The model django.contrib.postgres.fields.CICharField, django.contrib.postgres.fields.CIEmailField, and django.contrib.postgres.fields.CITextField are removed, except for support in historical migrations.

• The django.contrib.postgres.fields.CIText mixin is removed.

• The map_width and map_height attributes of BaseGeometryWidget are removed.

• The SimpleTestCase.assertFormsetError() method is removed.

• The TransactionTestCase.assertQuerysetEqual() method is removed.

• Support for passing encoded JSON string literals to JSONField and associated lookups and expressions is removed.

• Support for passing positional arguments to Signer and TimestampSigner is removed.

• The DEFAULT_FILE_STORAGE and STATICFILES_STORAGE settings is removed.

• The django.core.files.storage.get_storage_class() function is removed.