{"title":"Django 4.1 release notes","version":"dev","locale":"en","docname":"releases/4.1","url":"/en/dev/releases/4.1/","canonical":"https://djangodocs.dev/en/dev/releases/4.1/","summary":"Welcome to Django 4.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 4.1 release notesLink to this heading#

\n

August 3, 2022

\n

Welcome to Django 4.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 4.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
\n

Python compatibilityLink to this heading#

\n

Django 4.1 supports Python 3.8, 3.9, 3.10, and 3.11 (as of 4.1.3). We\nhighly recommend and only officially support the latest release of each\nseries.

\n
\n
\n

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

\n
\n

Asynchronous handlers for class-based viewsLink to this heading#

\n

View subclasses may now define async HTTP method handlers:

\n
Code
import asyncio\nfrom django.http import HttpResponse\nfrom django.views import View\n\n\nclass AsyncView(View):\n    async def get(self, request, *args, **kwargs):\n        # Perform view logic using await.\n        await asyncio.sleep(1)\n        return HttpResponse("Hello async world!")\n
\n

See Asynchronous class-based views for more details.

\n
\n
\n

Asynchronous ORM interfaceLink to this heading#

\n

QuerySet now provides an asynchronous interface for all data access\noperations. These are named as-per the existing synchronous operations but with\nan a prefix, for example acreate(), aget(), and so on.

\n

The new interface allows you to write asynchronous code without needing to wrap\nORM operations in sync_to_async():

\n
Code
async for author in Author.objects.filter(name__startswith="A"):\n    book = await author.books.afirst()\n
\n

Note that, at this stage, the underlying database operations remain\nsynchronous, with contributions ongoing to push asynchronous support down into\nthe SQL compiler, and integrate asynchronous database drivers. The new\nasynchronous queryset interface currently encapsulates the necessary\nsync_to_async() operations for you, and will allow your code to take\nadvantage of developments in the ORM’s asynchronous support as it evolves.

\n

See Asynchronous queries for details and limitations.

\n
\n
\n

Validation of ConstraintsLink to this heading#

\n

Check,\nunique, and exclusion constraints defined\nin the Meta.constraints option\nare now checked during model validation.

\n
\n
\n

Form rendering accessibilityLink to this heading#

\n

In order to aid users with screen readers, and other assistive technology, new\n<div> based form templates are available from this release. These provide\nmore accessible navigation than the older templates, and are able to correctly\ngroup related controls, such as radio-lists, into fieldsets.

\n

The new templates are recommended, and will become the default form rendering\nstyle when outputting a form, like {{ form }} in a template, from Django\n5.0.

\n

In order to ease adopting the new output style, the default form and formset\ntemplates are now configurable at the project level via the\nFORM_RENDERER setting.

\n

See the Forms section (below) for full details.

\n
\n\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

  • The admin dark mode CSS variables are now applied in a\nseparate stylesheet and template block.

    • \n

  • ModelAdmin List Filters providing custom FieldListFilter\nsubclasses can now control the query string value separator when filtering\nfor multiple values using the __in lookup.

    • \n

  • The admin history view\nis now paginated.

    • \n

  • Related widget wrappers now have a link to object’s change form.

    • \n

  • The AdminSite.get_app_list() method now allows changing the order of\napps and models on the admin index page.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n
    \n

  • The default iteration count for the PBKDF2 password hasher is increased from\n320,000 to 390,000.

    • \n

  • The RemoteUserBackend.configure_user() method now allows synchronizing\nuser attributes with attributes in a remote system such as an LDAP directory.

    • \n
\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

django.contrib.postgresLink to this heading#

\n\n
\n
\n

django.contrib.sitemapsLink to this heading#

\n
    \n

  • The default sitemap index template <sitemapindex> now includes the\n<lastmod> timestamp where available, through the new\nget_latest_lastmod() method. Custom\nsitemap index templates should be updated for the adjusted context\nvariables.

    • \n
\n
\n
\n

django.contrib.staticfilesLink to this heading#

\n\n
\n
\n

Database backendsLink to this heading#

\n
    \n

  • Third-party database backends can now specify the minimum required version of\nthe database using the DatabaseFeatures.minimum_database_version\nattribute which is a tuple (e.g. (10, 0) means “10.0”). If a minimum\nversion is specified, backends must also implement\nDatabaseWrapper.get_database_version(), which returns a tuple of the\ncurrent database version. The backend’s\nDatabaseWrapper.init_connection_state() method must call super() in\norder for the check to run.

    • \n
\n
\n
\n

FormsLink to this heading#

\n
    \n

  • The default template used to render forms when cast to a string, e.g. in\ntemplates as {{ form }}, is now configurable at the project-level by\nsetting form_template_name on\nthe class provided for FORM_RENDERER.

    \n

    Form.template_name is now a property deferring to the renderer, but\nmay be overridden with a string value to specify the template name per-form\nclass.

    \n

    Similarly, the default template used to render formsets can be specified via\nthe matching\nformset_template_name renderer\nattribute.

    \n
    • \n

  • The new div.html form template, referencing\nForm.template_name_div attribute, and matching Form.as_div()\nmethod, render forms using HTML <div> elements.

    \n

    This new output style is recommended over the existing\nas_table(), as_p() and as_ul() styles,\nas the template implements <fieldset> and <legend> to group related\ninputs and is easier for screen reader users to navigate.

    \n

    The div-based output will become the default rendering style from Django 5.0.

    \n
    • \n

  • In order to smooth adoption of the new <div> output style, two\ntransitional form renderer classes are available:\ndjango.forms.renderers.DjangoDivFormRenderer and\ndjango.forms.renderers.Jinja2DivFormRenderer, for the Django and Jinja2\ntemplate backends respectively.

    \n

    You can apply one of these via the FORM_RENDERER setting. For\nexample:

    \n
    Code
    FORM_RENDERER = "django.forms.renderers.DjangoDivFormRenderer"\n
    \n

    Once the <div> output style is the default, from Django 5.0, these\ntransitional renderers will be deprecated, for removal in Django 6.0. The\nFORM_RENDERER declaration can be removed at that time.

    \n
    • \n

  • If the new <div> output style is not appropriate for your project, you\nshould define a renderer subclass specifying\nform_template_name and\nformset_template_name for your\nrequired style, and set FORM_RENDERER accordingly.

    \n

    For example, for the <p> output style used by as_p(), you\nwould define a form renderer setting form_template_name to\n"django/forms/p.html" and formset_template_name to\n"django/forms/formsets/p.html".

    \n
    • \n

  • The new legend_tag() allows rendering field\nlabels in <legend> tags via the new tag argument of\nlabel_tag().

    • \n

  • The new edit_only argument for modelformset_factory() and\ninlineformset_factory() allows preventing new objects creation.

    • \n

  • The js and css class attributes of Media\nnow allow using hashable objects, not only path strings, as long as those\nobjects implement the __html__() method (typically when decorated with\nthe html_safe() decorator).

    • \n

  • The new BoundField.use_fieldset and Widget.use_fieldset\nattributes help to identify widgets where its inputs should be grouped in a\n<fieldset> with a <legend>.

    • \n

  • The error_messages argument for\nBaseFormSet now allows customizing\nerror messages for invalid number of forms by passing 'too_few_forms'\nand 'too_many_forms' keys.

    • \n

  • IntegerField, FloatField, and\nDecimalField now optionally accept a step_size\nargument. This is used to set the step HTML attribute, and is validated\non form submission.

    • \n
\n
\n
\n

InternationalizationLink to this heading#

\n
    \n

  • The i18n_patterns() function now supports\nlanguages with both scripts and regions.

    • \n
\n
\n
\n

Management CommandsLink to this heading#

\n\n
\n
\n

MigrationsLink to this heading#

\n
    \n

  • The new RenameIndex operation\nallows renaming indexes defined in the\nMeta.indexes or\nindex_together options.

    • \n

  • The migrations autodetector now generates\nRenameIndex operations instead of\nRemoveIndex and AddIndex, when renaming indexes defined in the\nMeta.indexes.

    • \n

  • The migrations autodetector now generates\nRenameIndex operations instead of\nAlterIndexTogether and AddIndex, when moving indexes defined in the\nMeta.index_together to the\nMeta.indexes.

    • \n
\n
\n
\n

ModelsLink to this heading#

\n
    \n

  • The order_by argument of the\nWindow expression now accepts string\nreferences to fields and transforms.

    • \n

  • The new CONN_HEALTH_CHECKS setting allows enabling health checks\nfor persistent database connections\nin order to reduce the number of failed requests, e.g. after database server\nrestart.

    • \n

  • QuerySet.bulk_create() now supports updating fields when a row\ninsertion fails uniqueness constraints. This is supported on MariaDB, MySQL,\nPostgreSQL, and SQLite 3.24+.

    • \n

  • QuerySet.iterator() now supports prefetching related objects as long\nas the chunk_size argument is provided. In older versions, no prefetching\nwas done.

    • \n

  • Q objects and querysets can now be combined using\n^ as the exclusive or (XOR) operator. XOR is natively supported\non MariaDB and MySQL. For databases that do not support XOR, the query\nwill be converted to an equivalent using AND, OR, and NOT.

    • \n

  • The new Field.non_db_attrs attribute\nallows customizing attributes of fields that don’t affect a column\ndefinition.

    • \n

  • On PostgreSQL, AutoField, BigAutoField, and SmallAutoField are\nnow created as identity columns rather than serial columns with sequences.

    • \n
\n
\n
\n

Requests and ResponsesLink to this heading#

\n\n
\n
\n

SecurityLink to this heading#

\n\n
\n
\n

SignalsLink to this heading#

\n\n
\n
\n

TemplatesLink to this heading#

\n
    \n

  • The HTML <script> element id attribute is no longer required when\nwrapping the json_script template filter.

    • \n

  • The cached template loader\nis now enabled in development, when DEBUG is True, and\nOPTIONS['loaders'] isn’t specified. You may\nspecify OPTIONS['loaders'] to override this, if necessary.

    • \n
\n
\n
\n

TestsLink to this heading#

\n\n
\n
\n

URLsLink to this heading#

\n\n
\n
\n

UtilitiesLink to this heading#

\n
    \n

  • SimpleLazyObject now supports addition operations.

    • \n

  • mark_safe() now preserves lazy objects.

    • \n
\n
\n
\n

ValidatorsLink to this heading#

\n
    \n

  • The new StepValueValidator checks if a value\nis an integral multiple of a given step size. This new validator is used for\nthe new step_size argument added to form fields representing numeric\nvalues.

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

Backwards incompatible changes in 4.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.gisLink to this heading#

\n\n
\n
\n

Dropped support for PostgreSQL 10Link to this heading#

\n

Upstream support for PostgreSQL 10 ends in November 2022. Django 4.1 supports\nPostgreSQL 11 and higher.

\n
\n
\n

Dropped support for MariaDB 10.2Link to this heading#

\n

Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB\n10.3 and higher.

\n
\n
\n

Admin changelist searches spanning multi-valued relationships changesLink to this heading#

\n

Admin changelist searches using multiple search terms are now applied in a\nsingle call to filter(), rather than in sequential filter() calls.

\n

For multi-valued relationships, this means that rows from the related model\nmust match all terms rather than any term. For example, if search_fields\nis set to ['child__name', 'child__age'], and a user searches for\n'Jamal 17', parent rows will be returned only if there is a relationship to\nsome 17-year-old child named Jamal, rather than also returning parents who\nmerely have a younger or older child named Jamal in addition to some other\n17-year-old.

\n

See the Spanning multi-valued relationships topic for more discussion of\nthis difference. In Django 4.0 and earlier,\nget_search_results() followed the\nsecond example query, but this undocumented behavior led to queries with\nexcessive joins.

\n
\n
\n

Reverse foreign key changes for unsaved model instancesLink to this heading#

\n

In order to unify the behavior with many-to-many relations for unsaved model\ninstances, a reverse foreign key now raises ValueError when calling\nrelated managers for\nunsaved objects.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 4.1Link to this heading#

\n
\n

Log out via GETLink to this heading#

\n

Logging out via GET requests to the built-in logout view is deprecated. Use POST requests\ninstead.

\n

If you want to retain the user experience of an HTML link, you can use a form\nthat is styled to appear as a link:

\n
Html
<form id="logout-form" method="post" action="{% url 'admin:logout' %}">\n  {% csrf_token %}\n  <button type="submit">{% translate "Log out" %}</button>\n</form>\n
\n
Css
#logout-form {\n  display: inline;\n}\n#logout-form button {\n  background: none;\n  border: none;\n  cursor: pointer;\n  padding: 0;\n  text-decoration: underline;\n}\n
\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features removed in 4.1Link to this heading#

\n

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

\n

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

\n\n
","rootId":"django-4-1-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 4.1","anchor":"what-s-new-in-django-4-1","children":[{"title":"Asynchronous handlers for class-based views","anchor":"asynchronous-handlers-for-class-based-views","children":[]},{"title":"Asynchronous ORM interface","anchor":"asynchronous-orm-interface","children":[]},{"title":"Validation of Constraints","anchor":"validation-of-constraints","children":[]},{"title":"Form rendering accessibility","anchor":"form-rendering-accessibility","children":[]},{"title":"CSRF_COOKIE_MASKED setting","anchor":"csrf-cookie-masked-setting","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.sitemaps","anchor":"django-contrib-sitemaps","children":[]},{"title":"django.contrib.staticfiles","anchor":"django-contrib-staticfiles","children":[]},{"title":"Database backends","anchor":"database-backends","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Internationalization","anchor":"internationalization","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Migrations","anchor":"migrations","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Security","anchor":"security","children":[]},{"title":"Signals","anchor":"signals","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"URLs","anchor":"urls","children":[]},{"title":"Utilities","anchor":"utilities","children":[]},{"title":"Validators","anchor":"validators","children":[]}]}]},{"title":"Backwards incompatible changes in 4.1","anchor":"backwards-incompatible-changes-in-4-1","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.gis","anchor":"id1","children":[]},{"title":"Dropped support for PostgreSQL 10","anchor":"dropped-support-for-postgresql-10","children":[]},{"title":"Dropped support for MariaDB 10.2","anchor":"dropped-support-for-mariadb-10-2","children":[]},{"title":"Admin changelist searches spanning multi-valued relationships changes","anchor":"admin-changelist-searches-spanning-multi-valued-relationships-changes","children":[]},{"title":"Reverse foreign key changes for unsaved model instances","anchor":"reverse-foreign-key-changes-for-unsaved-model-instances","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 4.1","anchor":"features-deprecated-in-4-1","children":[{"title":"Log out via GET","anchor":"log-out-via-get","children":[]},{"title":"Miscellaneous","anchor":"id2","children":[]}]},{"title":"Features removed in 4.1","anchor":"features-removed-in-4-1","children":[]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/4.1.1","title":"Django 4.1.1 release notes","url":"/en/dev/releases/4.1.1/"},"next":{"docname":"releases/4.0.10","title":"Django 4.0.10 release notes","url":"/en/dev/releases/4.0.10/"},"formats":{"html":"/en/dev/releases/4.1/","markdown":"/en/dev/releases/4.1.md","json":"/en/dev/releases/4.1.json"},"source":"https://github.com/django/django/blob/main/docs/releases/4.1.txt","official":"https://docs.djangoproject.com/en/dev/releases/4.1/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1"],"inLocales":["en"]}