Django 4.1 release notes

Welcome to Django 4.1!

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

See the guide if you’re updating an existing project.

Django 4.1 supports Python 3.8, 3.9, and 3.10. We highly recommend and only officially support the latest release of each series.

View subclasses may now define async HTTP method handlers:

See Asynchronous class-based views for more details.

Asynchronous ORM interface

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

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

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

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

See Asynchronous queries for details and limitations.

Validation of Constraints

Check, , and exclusion constraints defined in the option are now checked during model validation.

Form rendering accessibility

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

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

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

See for full details.

CSRF_COOKIE_MASKED setting

The new transitional setting allows specifying whether to mask the CSRF cookie.

CsrfViewMiddleware no longer masks the CSRF cookie like it does the CSRF token in the DOM. If you are upgrading multiple instances of the same project to Django 4.1, you should set to True during the transition, in order to allow compatibility with the older versions of Django. Once the transition to 4.1 is complete you can stop overriding CSRF_COOKIE_MASKED.

This setting is deprecated as of this release and will be removed in Django 5.0.

django.contrib.admin

• The admin are now applied in a separate stylesheet and template block.
• ModelAdmin List Filters providing custom FieldListFilter subclasses can now control the query string value separator when filtering for multiple values using the __in lookup.
• The admin is now paginated.
• Related widget wrappers now have a link to object’s change form.
• The AdminSite.get_app_list() method now allows changing the order of apps and models on the admin index page.

django.contrib.auth

• The default iteration count for the PBKDF2 password hasher is increased from 320,000 to 390,000.
• The method now allows synchronizing user attributes with attributes in a remote system such as an LDAP directory.

• The new GEOSGeometry.make_valid() method allows converting invalid geometries to valid ones.
• The new clone argument for allows creating a normalized clone of the geometry.

• The new BitXor() aggregate function returns an int of the bitwise XOR of all non-null input values.
• now supports covering indexes on PostgreSQL 14+.
• ExclusionConstraint now supports covering exclusion constraints using SP-GiST indexes on PostgreSQL 14+.
• The new default_bounds attribute of and DecimalRangeField allows specifying bounds for list and tuple inputs.
• now allows specifying operator classes with the OpClass() expression.

django.contrib.sitemaps

• The default sitemap index template <sitemapindex> now includes the <lastmod> timestamp where available, through the new method. Custom sitemap index templates should be updated for the adjusted context variables.

django.contrib.staticfiles

Database backends

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

Forms

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

  is now a property deferring to the renderer, but may be overridden with a string value to specify the template name per-form class.

• The new div.html form template, referencing Form.template_name_div attribute, and matching method, render forms using HTML <div> elements.

  This new output style is recommended over the existing as_table(), and as_ul() styles, as the template implements <fieldset> and <legend> to group related inputs and is easier for screen reader users to navigate.

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

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

  You can apply one of these via the setting. For example:

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

• If the new <div> output style is not appropriate for your project, you should define a renderer subclass specifying form_template_name and for your required style, and set FORM_RENDERER accordingly.

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

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

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

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

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

• The error_messages argument for now allows customizing error messages for invalid number of forms by passing 'too_few_forms' and 'too_many_forms' keys.

• IntegerField, , and DecimalField now optionally accept a step_size argument. This is used to set the step HTML attribute, and is validated on form submission.

Internationalization

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

Management Commands

• makemigrations —no-input now logs default answers and reasons why migrations cannot be created.
• The new option diverts log output and input prompts to stderr, writing only paths of generated migration files to stdout.
• The new migrate —prune option allows deleting nonexistent migrations from the django_migrations table.
• Python files created by , startapp, , makemigrations, and are now formatted using the black command if it is present on your PATH.
• The new optimizemigration command allows optimizing operations for a migration.

Migrations

• The new RenameIndex operation allows renaming indexes defined in the or index_together options.
• The migrations autodetector now generates operations instead of RemoveIndex and AddIndex, when renaming indexes defined in the Meta.indexes.
• The migrations autodetector now generates operations instead of AlterIndexTogether and AddIndex, when moving indexes defined in the Meta.index_together to the .

Models

• The order_by argument of the expression now accepts string references to fields and transforms.
• The new CONN_HEALTH_CHECKS setting allows enabling health checks for in order to reduce the number of failed requests, e.g. after database server restart.
• QuerySet.bulk_create() now supports updating fields when a row insertion fails uniqueness constraints. This is supported on MariaDB, MySQL, PostgreSQL, and SQLite 3.24+.
• now supports prefetching related objects as long as the chunk_size argument is provided. In older versions, no prefetching was done.
• Q objects and querysets can now be combined using ^ as the exclusive or (XOR) operator. XOR is natively supported on MariaDB and MySQL. For databases that do not support XOR, the query will be converted to an equivalent using AND, OR, and .
• The new attribute allows customizing attributes of fields that don’t affect a column definition.
• On PostgreSQL, AutoField, BigAutoField, and SmallAutoField are now created as identity columns rather than serial columns with sequences.

Requests and Responses

• now supports timedelta objects for the max_age argument.

Security

• The new SECRET_KEY_FALLBACKS setting allows providing a list of values for secret key rotation.
• The setting now supports a comma-separated list of protocols in the header value.

Signals

• The and post_delete signals now dispatch the origin of the deletion.

Templates

• The HTML <script> element id attribute is no longer required when wrapping the json_script template filter.
• The is now enabled in development, when DEBUG is True, and isn’t specified. You may specify OPTIONS['loaders'] to override this, if necessary.

Tests

• The now supports running tests in parallel on macOS, Windows, and any other systems where the default multiprocessing start method is spawn.
• A nested atomic block marked as durable in now raises a RuntimeError, the same as outside of tests.
• SimpleTestCase.assertFormError() and now support passing a form/formset object directly.

URLs

• The new attribute stores the captured keyword arguments, as parsed from the URL.
• The new ResolverMatch.extra_kwargs attribute stores the additional keyword arguments passed to the view function.

Utilities

• SimpleLazyObject now supports addition operations.
• mark_safe() now preserves lazy objects.

Validators

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

Database backend API

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

• BaseDatabaseFeatures.has_case_insensitive_like is changed from True to False to reflect the behavior of most databases.
• DatabaseIntrospection.get_key_columns() is removed. Use DatabaseIntrospection.get_relations() instead.
• DatabaseOperations.ignore_conflicts_suffix_sql() method is replaced by DatabaseOperations.on_conflict_suffix_sql() that accepts the fields, on_conflict, update_fields, and unique_fields arguments.
• The ignore_conflicts argument of the DatabaseOperations.insert_statement() method is replaced by on_conflict that accepts django.db.models.constants.OnConflict.
• DatabaseOperations._convert_field_to_tz() is replaced by DatabaseOperations._convert_sql_to_tz() that accepts the sql, params, and tzname arguments.
• Several date and time methods on DatabaseOperations now take sql and params arguments instead of field_name and return 2-tuple containing some SQL and the parameters to be interpolated into that SQL. The changed methods have these new signatures:
  • DatabaseOperations.date_extract_sql(lookup_type, sql, params)
  • DatabaseOperations.datetime_extract_sql(lookup_type, sql, params, tzname)
  • DatabaseOperations.time_extract_sql(lookup_type, sql, params)
  • DatabaseOperations.date_trunc_sql(lookup_type, sql, params, tzname=None)
  • DatabaseOperations.datetime_trunc_sql(self, lookup_type, sql, params, tzname)
  • DatabaseOperations.time_trunc_sql(lookup_type, sql, params, tzname=None)
  • DatabaseOperations.datetime_cast_date_sql(sql, params, tzname)
  • DatabaseOperations.datetime_cast_time_sql(sql, params, tzname)

• Support for GDAL 2.1 is removed.
• Support for PostGIS 2.4 is removed.

Dropped support for PostgreSQL 10

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

Dropped support for MariaDB 10.2

Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB 10.3 and higher.

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

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

See the Spanning multi-valued relationships topic for more discussion of this difference. In Django 4.0 and earlier, followed the second example query, but this undocumented behavior led to queries with excessive joins.

Reverse foreign key changes for unsaved model instances

Miscellaneous

• The Django test runner now returns a non-zero error code for unexpected successes from tests marked with unittest.expectedFailure().
• no longer masks the CSRF cookie like it does the CSRF token in the DOM.
• CsrfViewMiddleware now uses request.META['CSRF_COOKIE'] for storing the unmasked CSRF secret rather than a masked version. This is an undocumented, private API.
• The and inlines attributes now default to an empty tuple rather than an empty list to discourage unintended mutation.
• The type="text/css" attribute is no longer included in <link> tags for CSS .
• formset:added and formset:removed JavaScript events are now pure JavaScript events and don’t depend on jQuery. See Inline form events for more details on the change.
• The exc_info argument of the undocumented django.utils.log.log_response() function is replaced by exception.
• The size argument of the undocumented django.views.static.was_modified_since() function is removed.
• The admin log out UI now uses POST requests.
• The undocumented InlineAdminFormSet.non_form_errors property is replaced by the non_form_errors() method. This is consistent with BaseFormSet.
• As per , the cached template loader is now enabled in development. You may specify OPTIONS['loaders'] to override this, if necessary.
• The undocumented django.contrib.auth.views.SuccessURLAllowedHostsMixin mixin is replaced by RedirectURLMixin.
• BaseConstraint subclasses must implement method to allow those constraints to be used for validation.
• The undocumented , URLResolver._callback_strs, and URLPattern.lookup_str() are moved to django.contrib.admindocs.utils.
• The Model.full_clean() method now converts an exclude value to a set. It’s also preferable to pass an exclude value as a set to the , Model.full_clean(), , and Model.validate_constraints() methods.
• The minimum supported version of asgiref is increased from 3.4.1 to 3.5.2.

Log out via GET

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

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

<form id="logout-form" method="post" action="{% url 'admin:logout' %}">
  {% csrf_token %}
  <button type="submit">{% translate "Log out" %}</button>
</form>

Miscellaneous

• The context for sitemap index templates of a flat list of URLs is deprecated. Custom sitemap index templates should be updated for the adjusted context variables, expecting a list of objects with location and optional lastmod attributes.

• CSRF_COOKIE_MASKED transitional setting is deprecated.

• The name argument of is deprecated as it’s unnecessary as of Python 3.6.

• The opclasses argument of django.contrib.postgres.constraints.ExclusionConstraint is deprecated in favor of using OpClass() in . To use it, you need to add 'django.contrib.postgres' in your INSTALLED_APPS.

  After making this change, will generate a new migration with two operations: RemoveConstraint and AddConstraint. Since this change has no effect on the database schema, the SeparateDatabaseAndState operation can be used to only update the migration state without running any SQL. Move the generated operations into the state_operations argument of . For example:

  class Migration(migrations.Migration):
      ...
      operations = [
          migrations.SeparateDatabaseAndState(
              database_operations=[],
              state_operations=[
                  migrations.RemoveConstraint(
                      ...
                  ),
                  migrations.AddConstraint(
                      ...
                  ),
              ],
          ),
      ]

• The undocumented ability to pass errors=None to SimpleTestCase.assertFormError() and is deprecated. Use errors=[] instead.

• django.contrib.sessions.serializers.PickleSerializer is deprecated due to the risk of remote code execution.

• The usage of QuerySet.iterator() on a queryset that prefetches related objects without providing the chunk_size argument is deprecated. In older versions, no prefetching was done. Providing a value for chunk_size signifies that the additional query per chunk needed to prefetch is desired.

• Passing unsaved model instances to related filters is deprecated. In Django 5.0, the exception will be raised.

• created=True is added to the signature of RemoteUserBackend.configure_user(). Support for RemoteUserBackend subclasses that do not accept this argument is deprecated.

• The alias to datetime.timezone.utc is deprecated. Use directly.

• Passing a response object and a form/formset name to SimpleTestCase.assertFormError() and assertFormsetError() is deprecated. Use:

  or pass the form/formset object directly instead.

• The undocumented django.contrib.gis.admin.OpenLayersWidget is deprecated.

• django.contrib.auth.hashers.CryptPasswordHasher is deprecated.

• The ability to pass nulls_first=False or nulls_last=False to Expression.asc() and Expression.desc() methods, and the OrderBy expression is deprecated. Use None instead.

• The "django/forms/default.html" and "django/forms/formsets/default.html" templates which are a proxy to the table-based templates are deprecated. Use the specific template instead.

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

• Support for assigning objects which don’t support creating deep copies with copy.deepcopy() to class attributes in TestCase.setUpTestData() is removed.
• Support for using a boolean value in BaseCommand.requires_system_checks is removed.
• The whitelist argument and domain_whitelist attribute of django.core.validators.EmailValidator are removed.
• The default_app_config application configuration variable is removed.
• TransactionTestCase.assertQuerysetEqual() no longer calls repr() on a queryset when compared to string values.
• The backend is removed.