{"title":"Django 6.1 release notes","version":"dev","locale":"en","docname":"releases/6.1","url":"/en/dev/releases/6.1/","canonical":"https://djangodocs.dev/en/dev/releases/6.1/","summary":"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…","html":"

Django 6.1 release notesLink to this heading#

\n

August 5, 2026

\n

Welcome to Django 6.1!

\n

These release notes cover the new features, as well as\nsome backwards incompatible changes you’ll\nwant to be aware of when upgrading from Django 6.0 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

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

\n
\n

Python compatibilityLink to this heading#

\n

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

\n
\n
\n

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

\n
\n

Model field fetch modesLink to this heading#

\n

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

\n

Django provides three fetch modes:

\n
    \n

  1. FETCH_ONE, the default, fetches the missing field for the current\ninstance only. This mode represents Django’s existing behavior.

    2. \n

  2. FETCH_PEERS fetches a missing field for all instances that came from\nthe same QuerySet.

    \n

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

    \n
    3. \n

  3. FETCH_RAISE raises a FieldFetchBlocked\nexception.

    \n

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

    \n
    4. \n
\n

Use the new method QuerySet.fetch_mode() to set the fetch mode for model\ninstances fetched by the QuerySet:

\n
Code
from django.db import models\n\nbooks = Book.objects.fetch_mode(models.FETCH_PEERS)\nfor book in books:\n    print(book.author.name)\n
\n

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

\n
    \n

  1. Fetch all books.

    2. \n

  2. Fetch associated authors.

    3. \n
\n

See fetch modes for more details.

\n
\n
\n

Database-level delete options for ForeignKey.on_deleteLink to this heading#

\n

ForeignKey.on_delete now supports database-level delete options:

\n\n

These options handle deletion logic entirely within the database, using the SQL\nON DELETE clause. They are thus more efficient than the existing\nPython-level options, as Django does not need to load objects before deleting\nthem. As a consequence, the DB_CASCADE option does\nnot trigger the pre_delete or post_delete signals.

\n
\n
\n

MailersLink to this heading#

\n

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

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

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

\n

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

\n

You can opt into the new feature at any time before Django 2028; see\nMigrating email to mailers. To ease the transition,\nmail.mailers["default"] works with\neither MAILERS or the deprecated EMAIL_BACKEND setting\ndefined. The deprecated get_connection() function will\nalso return an instance of the default mailer when MAILERS is\ndefined.

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

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

    • \n

  • The admin’s FilteredSelectMultiple widget now uses <optgroup>s to\npreserve named groups (e.g.\nchoices=[("Group", [("1", "Item")]), ...]).

    • \n

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

    • \n

  • The delete_confirmation_max_display\noption allows customizing how many objects are displayed on admin delete\nconfirmation pages and inline protected deletion errors before the remainder\nis truncated. The default is None (no truncation).

    • \n

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

    \n
      \n

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

      • \n

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

      • \n

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

      • \n

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

      • \n
    \n
    • \n

  • list_display now uses boolean icons\nfor boolean fields on related models.

    • \n

  • The new location keyword argument of the\naction() decorator specifies which admin views\nthe action is available on. The action is available on the admin change list\npage by default. It can also be available on the admin change form. See\nControlling where actions are available for details.

    • \n

  • The new description_plural keyword argument of the\naction() decorator specifies a human-readable\ndescription for actions on the admin change list page. Defaults to the\ndescription value. This is useful when the action is available on both\nthe admin change list and admin change form.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n
    \n

  • The isempty lookup and\nIsEmpty()\ndatabase function are now supported on SpatiaLite.

    • \n

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

    • \n

  • OpenLayersWidget is now based on\nOpenLayers 10.9.0 (previously 7.2.2).

    • \n
\n
\n
\n

django.contrib.postgresLink to this heading#

\n\n
\n
\n

django.contrib.sessionsLink to this heading#

\n\n
\n
\n

CSPLink to this heading#

\n
    \n

  • The new csp_nonce_attr template tag renders the CSP nonce attribute\non <script> and <link> elements, or renders a\nMedia object’s assets with the nonce applied, when the\ncsp() context processor is\nconfigured. See Nonce usage for details.

    • \n

  • A new security.W027 system check warns when\nContentSecurityPolicyMiddleware is enabled\nwith CSP.NONCE in a CSP policy but\ndjango.template.context_processors.csp is not configured.

    • \n

  • CSP nonce attributes are now added on <script>, <style>, and\n<link> elements in admin templates and all built-in templates when the\ncsp() context processor is\nconfigured. See Nonce config for setup instructions.

    • \n
\n
\n
\n

EmailLink to this heading#

\n
    \n

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

    • \n

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

    • \n
\n
\n
\n

FormsLink to this heading#

\n
    \n

  • The new asset object Stylesheet is available for\nadding custom HTML-attributes to stylesheet links in form media. See\npaths as objects for more details.

    • \n

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

    • \n

  • FilePathField now provides a\nset_choices() method to scan the\ndirectory at path and refresh the\nfield’s choices. This allows per-request refreshing when called in a form’s\n__init__().

    • \n
\n
\n
\n

Generic ViewsLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

Management CommandsLink to this heading#

\n
    \n

  • Management commands now set ArgumentParser's\nsuggest_on_error argument to True by default on Python 3.14, enabling\nsuggestions for incorrectly typed subcommand names and argument choices.

    • \n

  • The loaddata command now calls\nm2m_changed signals with raw=True when\nloading fixtures.

    • \n

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

    • \n
\n
\n
\n

ModelsLink to this heading#

\n\n
\n
\n

Requests and ResponsesLink to this heading#

\n\n
\n
\n

SecurityLink to this heading#

\n\n
\n
\n

SerializationLink to this heading#

\n
    \n

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

    • \n

  • The XML deserializer now raises\nSuspiciousOperation when it encounters\nunexpected nested tags.

    • \n
\n
\n
\n

TasksLink to this heading#

\n
    \n

  • The task() decorator now accepts **kwargs, which are\nforwarded to the backend’s\ntask_class.

    • \n

  • Task and TaskResult instances\ncan now be pickled and unpickled.

    • \n
\n
\n
\n

TestsLink to this heading#

\n\n
\n
\n

UtilitiesLink to this heading#

\n
    \n

  • parse_duration() now supports ISO 8601\ntime periods expressed in weeks (PnW).

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

Backwards incompatible changes in 6.1Link 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.adminLink to this heading#

\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.postgresLink to this heading#

\n\n
\n
\n

EmailLink to this heading#

\n\n
\n
\n

ModelsLink to this heading#

\n\n
\n
\n

System checksLink to this heading#

\n\n
\n
\n

Dropped support for PostgreSQL 14Link to this heading#

\n

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

\n
\n
\n

Dropped support for MySQL < 8.4Link to this heading#

\n

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

\n
\n
\n

Dropped support for MariaDB < 10.11Link to this heading#

\n

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

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 6.1Link to this heading#

\n
\n

EmailLink to this heading#

\n\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features removed in 6.1Link to this heading#

\n

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

\n

See Features deprecated in 5.2 for details on these changes, including how\nto remove usage of these features.

\n\n
","rootId":"django-6-1-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 6.1","anchor":"what-s-new-in-django-6-1","children":[{"title":"Model field fetch modes","anchor":"model-field-fetch-modes","children":[]},{"title":"Database-level delete options for ForeignKey.on_delete","anchor":"database-level-delete-options-for-foreignkey-on-delete","children":[]},{"title":"Mailers","anchor":"mailers","children":[]},{"title":"Minor features","anchor":"minor-features","children":[{"title":"django.contrib.admin","anchor":"django-contrib-admin","children":[]},{"title":"django.contrib.auth","anchor":"django-contrib-auth","children":[]},{"title":"django.contrib.gis","anchor":"django-contrib-gis","children":[]},{"title":"django.contrib.postgres","anchor":"django-contrib-postgres","children":[]},{"title":"django.contrib.sessions","anchor":"django-contrib-sessions","children":[]},{"title":"CSP","anchor":"csp","children":[]},{"title":"Email","anchor":"email","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Generic Views","anchor":"generic-views","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Security","anchor":"security","children":[]},{"title":"Serialization","anchor":"serialization","children":[]},{"title":"Tasks","anchor":"tasks","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"Utilities","anchor":"utilities","children":[]}]}]},{"title":"Backwards incompatible changes in 6.1","anchor":"backwards-incompatible-changes-in-6-1","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.admin","anchor":"id1","children":[]},{"title":"django.contrib.auth","anchor":"id2","children":[]},{"title":"django.contrib.gis","anchor":"id3","children":[]},{"title":"django.contrib.postgres","anchor":"id4","children":[]},{"title":"Email","anchor":"id5","children":[]},{"title":"Models","anchor":"id6","children":[]},{"title":"System checks","anchor":"system-checks","children":[]},{"title":"Dropped support for PostgreSQL 14","anchor":"dropped-support-for-postgresql-14","children":[]},{"title":"Dropped support for MySQL < 8.4","anchor":"dropped-support-for-mysql-8-4","children":[]},{"title":"Dropped support for MariaDB < 10.11","anchor":"dropped-support-for-mariadb-10-11","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 6.1","anchor":"features-deprecated-in-6-1","children":[{"title":"Email","anchor":"mailers-deprecations","children":[]},{"title":"Miscellaneous","anchor":"id8","children":[]}]},{"title":"Features removed in 6.1","anchor":"features-removed-in-6-1","children":[]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/6.1.1","title":"Django 6.1.1 release notes","url":"/en/dev/releases/6.1.1/"},"next":{"docname":"releases/6.0.9","title":"Django 6.0.9 release notes","url":"/en/dev/releases/6.0.9/"},"formats":{"html":"/en/dev/releases/6.1/","markdown":"/en/dev/releases/6.1.md","json":"/en/dev/releases/6.1.json"},"source":"https://github.com/django/django/blob/main/docs/releases/6.1.txt","official":"https://docs.djangoproject.com/en/dev/releases/6.1/","inVersions":["dev","6.1"],"inLocales":["en"]}