Django 3.1 release notes

August 4, 2020

Welcome to Django 3.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 3.0 or earlier. We’ve dropped some features that have reached the end of their deprecation cycle, and we’ve begun the deprecation process for some features.

See the Upgrading Django to a newer version guide if you’re updating an existing project.

Python compatibility

Django 3.1 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.1.3). We highly recommend and only officially support the latest release of each series.

What’s new in Django 3.1

Asynchronous views and middleware support

Django now supports a fully asynchronous request path, including:

To get started with async views, you need to declare a view using async def:

async def my_view(request):
    await asyncio.sleep(0.5)
    return HttpResponse('Hello, async world!')

All asynchronous features are supported whether you are running under WSGI or ASGI mode. However, there will be performance penalties using async code in WSGI mode. You can read more about the specifics in Asynchronous support documentation.

You are free to mix async and sync views, middleware, and tests as much as you want. Django will ensure that you always end up with the right execution context. We expect most projects will keep the majority of their views synchronous, and only have a select few running in async mode - but it is entirely your choice.

Django’s ORM, cache layer, and other pieces of code that do long-running network calls do not yet support async access. We expect to add support for them in upcoming releases. Async views are ideal, however, if you are doing a lot of API or HTTP calls inside your view, you can now natively do all those HTTP calls in parallel to considerably speed up your view’s execution.

Asynchronous support should be entirely backwards-compatible and we have tried to ensure that it has no speed regressions for your existing, synchronous code. It should have no noticeable effect on any existing Django projects.

JSONField for all supported database backends

Django now includes models.JSONField and forms.JSONField that can be used on all supported database backends. Both fields support the use of custom JSON encoders and decoders. The model field supports the introspection, lookups, and transforms that were previously PostgreSQL-only:

from django.db import models

class ContactInfo(models.Model):
    data = models.JSONField()

ContactInfo.objects.create(data={
    'name': 'John',
    'cities': ['London', 'Cambridge'],
    'pets': {'dogs': ['Rufus', 'Meg']},
})
ContactInfo.objects.filter(
    data__name='John',
    data__pets__has_key='dogs',
    data__cities__contains='London',
).delete()

If your project uses django.contrib.postgres.fields.JSONField, plus the related form field and transforms, you should adjust to use the new fields, and generate and apply a database migration. For now, the old fields and transforms are left as a reference to the new ones and are deprecated as of this release.

DEFAULT_HASHING_ALGORITHM settings

The new DEFAULT_HASHING_ALGORITHM transitional setting allows specifying the default hashing algorithm to use for encoding cookies, password reset tokens in the admin site, user sessions, and signatures created by django.core.signing.Signer and django.core.signing.dumps().

Support for SHA-256 was added in Django 3.1. If you are upgrading multiple instances of the same project to Django 3.1, you should set DEFAULT_HASHING_ALGORITHM to 'sha1' during the transition, in order to allow compatibility with the older versions of Django. Note that this requires Django 3.1.1+. Once the transition to 3.1 is complete you can stop overriding DEFAULT_HASHING_ALGORITHM.

This setting is deprecated as of this release, because support for tokens, cookies, sessions, and signatures that use SHA-1 algorithm will be removed in Django 4.0.

Minor features

django.contrib.admin

  • The new django.contrib.admin.EmptyFieldListFilter for ModelAdmin.list_filter allows filtering on empty values (empty strings and nulls) in the admin changelist view.

  • Filters in the right sidebar of the admin changelist view now contain a link to clear all filters.

  • The admin now has a sidebar on larger screens for easier navigation. It is enabled by default but can be disabled by using a custom AdminSite and setting AdminSite.enable_nav_sidebar to False.

    Rendering the sidebar requires access to the current request in order to set CSS and ARIA role affordances. This requires using 'django.template.context_processors.request' in the 'context_processors' option of OPTIONS.

  • Initially empty extra inlines can now be removed, in the same way as dynamically created ones.

  • XRegExp is upgraded from version 2.0.0 to 3.2.0.

  • jQuery is upgraded from version 3.4.1 to 3.5.1.

  • Select2 library is upgraded from version 4.0.7 to 4.0.13.

django.contrib.auth

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

  • The new PASSWORD_RESET_TIMEOUT setting allows defining the number of seconds a password reset link is valid for. This is encouraged instead of the deprecated PASSWORD_RESET_TIMEOUT_DAYS setting, which will be removed in Django 4.0.

  • The password reset mechanism now uses the SHA-256 hashing algorithm. Support for tokens that use the old hashing algorithm remains until Django 4.0.

  • AbstractBaseUser.get_session_auth_hash() now uses the SHA-256 hashing algorithm. Support for user sessions that use the old hashing algorithm remains until Django 4.0.

django.contrib.contenttypes

django.contrib.gis

django.contrib.humanize

  • intword template filter now supports negative integers.

django.contrib.postgres

django.contrib.sessions

  • The SESSION_COOKIE_SAMESITE setting now allows 'None' (string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.

django.contrib.staticfiles

Cache

CSRF

  • The CSRF_COOKIE_SAMESITE setting now allows 'None' (string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.

Email

Error Reporting

File Storage

  • FileSystemStorage.save() method now supports pathlib.Path.

  • FileField and ImageField now accept a callable for storage. This allows you to modify the used storage at runtime, selecting different storages for different environments, for example.

Forms

Internationalization

  • The LANGUAGE_COOKIE_SAMESITE setting now allows 'None' (string) value to explicitly state that the cookie is sent with all same-site and cross-site requests.

  • Added support and translations for the Algerian Arabic, Igbo, Kyrgyz, Tajik, and Turkmen languages.

Management Commands

  • The new check --database option allows specifying database aliases for running the database system checks. Previously these checks were enabled for all configured DATABASES by passing the database tag to the command.

  • The new migrate --check option makes the command exit with a non-zero status when unapplied migrations are detected.

  • The new returncode argument for CommandError allows customizing the exit status for management commands.

  • The new dbshell -- ARGUMENTS option allows passing extra arguments to the command-line client for the database.

  • The flush and sqlflush commands now include SQL to reset sequences on SQLite.

Models

  • The new ExtractIsoWeekDay function extracts ISO-8601 week days from DateField and DateTimeField, and the new iso_week_day lookup allows querying by an ISO-8601 day of week.

  • QuerySet.explain() now supports:

    • TREE format on MySQL 8.0.16+,

    • analyze option on MySQL 8.0.18+ and MariaDB.

  • Added PositiveBigIntegerField which acts much like a PositiveIntegerField except that it only allows values under a certain (database-dependent) limit. Values from 0 to 9223372036854775807 are safe in all databases supported by Django.

  • The new RESTRICT option for on_delete argument of ForeignKey and OneToOneField emulates the behavior of the SQL constraint ON DELETE RESTRICT.

  • CheckConstraint.check now supports boolean expressions.

  • The RelatedManager.add(), create(), and set() methods now accept callables as values in the through_defaults argument.

  • The new is_dst parameter of the QuerySet.datetimes() determines the treatment of nonexistent and ambiguous datetimes.

  • The new F expression bitxor() method allows bitwise XOR operation.

  • QuerySet.bulk_create() now sets the primary key on objects when using MariaDB 10.5+.

  • The DatabaseOperations.sql_flush() method now generates more efficient SQL on MySQL by using DELETE instead of TRUNCATE statements for tables which don’t require resetting sequences.

  • SQLite functions are now marked as deterministic on Python 3.8+. This allows using them in check constraints and partial indexes.

  • The new UniqueConstraint.deferrable attribute allows creating deferrable unique constraints.

Pagination

  • Paginator can now be iterated over to yield its pages.

Requests and Responses

Security

Templates

  • The renamed translate and blocktranslate template tags are introduced for internationalization in template code. The older trans and blocktrans template tags aliases continue to work, and will be retained for the foreseeable future.

  • The include template tag now accepts iterables of template names.

Tests

  • SimpleTestCase now implements the debug() method to allow running a test without collecting the result and catching exceptions. This can be used to support running tests under a debugger.

  • The new MIGRATE test database setting allows disabling of migrations during a test database creation.

  • Django test runner now supports a test --buffer option to discard output for passing tests.

  • DiscoverRunner now skips running the system checks on databases not referenced by tests.

  • TransactionTestCase teardown is now faster on MySQL due to flush command improvements. As a side effect the latter doesn’t automatically reset sequences on teardown anymore. Enable TransactionTestCase.reset_sequences if your tests require this feature.

URLs

  • Path converters can now raise ValueError in to_url() to indicate no match when reversing URLs.

Utilities

Miscellaneous

  • The SQLite backend now supports pathlib.Path for the NAME setting.

  • The settings.py generated by the startproject command now uses pathlib.Path instead of os.path for building filesystem paths.

  • The TIME_ZONE setting is now allowed on databases that support time zones.

Backwards incompatible changes in 3.1

Database backend API

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

  • DatabaseOperations.fetch_returned_insert_columns() now requires an additional returning_params argument.

  • connection.timezone property is now 'UTC' by default, or the TIME_ZONE when USE_TZ is True on databases that support time zones. Previously, it was None on databases that support time zones.

  • connection._nodb_connection property is changed to the connection._nodb_cursor() method and now returns a context manager that yields a cursor and automatically closes the cursor and connection upon exiting the with statement.

  • DatabaseClient.runshell() now requires an additional parameters argument as a list of extra arguments to pass on to the command-line client.

  • The sequences positional argument of DatabaseOperations.sql_flush() is replaced by the boolean keyword-only argument reset_sequences. If True, the sequences of the truncated tables will be reset.

  • The allow_cascade argument of DatabaseOperations.sql_flush() is now a keyword-only argument.

  • The using positional argument of DatabaseOperations.execute_sql_flush() is removed. The method now uses the database of the called instance.

  • Third-party database backends must implement support for JSONField or set DatabaseFeatures.supports_json_field to False. If storing primitives is not supported, set DatabaseFeatures.supports_primitives_in_json_field to False. If there is a true datatype for JSON, set DatabaseFeatures.has_native_json_field to True. If jsonfield.contains and jsonfield.contained_by are not supported, set DatabaseFeatures.supports_json_field_contains to False.

  • Third party database backends must implement introspection for JSONField or set can_introspect_json_field to False.

Dropped support for MariaDB 10.1

Upstream support for MariaDB 10.1 ends in October 2020. Django 3.1 supports MariaDB 10.2 and higher.

contrib.admin browser support

The admin no longer supports the legacy Internet Explorer browser. See the admin FAQ for details on supported browsers.

AbstractUser.first_name max_length increased to 150

A migration for django.contrib.auth.models.User.first_name is included. If you have a custom user model inheriting from AbstractUser, you’ll need to generate and apply a database migration for your user model.

If you want to preserve the 30 character limit for first names, use a custom form:

from django import forms
from django.contrib.auth.forms import UserChangeForm

class MyUserChangeForm(UserChangeForm):
    first_name = forms.CharField(max_length=30, required=False)

If you wish to keep this restriction in the admin when editing users, set UserAdmin.form to use this form:

from django.contrib.auth.admin import UserAdmin
from django.contrib.auth.models import User

class MyUserAdmin(UserAdmin):
    form = MyUserChangeForm

admin.site.unregister(User)
admin.site.register(User, MyUserAdmin)

Miscellaneous

  • The cache keys used by cache and generated by make_template_fragment_key() are different from the keys generated by older versions of Django. After upgrading to Django 3.1, the first request to any previously cached template fragment will be a cache miss.

  • The logic behind the decision to return a redirection fallback or a 204 HTTP response from the set_language() view is now based on the Accept HTTP header instead of the X-Requested-With HTTP header presence.

  • The compatibility imports of django.core.exceptions.EmptyResultSet in django.db.models.query, django.db.models.sql, and django.db.models.sql.datastructures are removed.

  • The compatibility import of django.core.exceptions.FieldDoesNotExist in django.db.models.fields is removed.

  • The compatibility imports of django.forms.utils.pretty_name() and django.forms.boundfield.BoundField in django.forms.forms are removed.

  • The compatibility imports of Context, ContextPopException, and RequestContext in django.template.base are removed.

  • The compatibility import of django.contrib.admin.helpers.ACTION_CHECKBOX_NAME in django.contrib.admin is removed.

  • The STATIC_URL and MEDIA_URL settings set to relative paths are now prefixed by the server-provided value of SCRIPT_NAME (or / if not set). This change should not affect settings set to valid URLs or absolute paths.

  • ConditionalGetMiddleware no longer adds the ETag header to responses with an empty content.

  • django.utils.decorators.classproperty() decorator is made public and moved to django.utils.functional.classproperty().

  • floatformat template filter now outputs (positive) 0 for negative numbers which round to zero.

  • Meta.ordering and Meta.unique_together options on models in django.contrib modules that were formerly tuples are now lists.

  • The admin calendar widget now handles two-digit years according to the Open Group Specification, i.e. values between 69 and 99 are mapped to the previous century, and values between 0 and 68 are mapped to the current century.

  • Date-only formats are removed from the default list for DATETIME_INPUT_FORMATS.

  • The FileInput widget no longer renders with the required HTML attribute when initial data exists.

  • The undocumented django.views.debug.ExceptionReporterFilter class is removed. As per the Custom error reports documentation, classes to be used with DEFAULT_EXCEPTION_REPORTER_FILTER need to inherit from django.views.debug.SafeExceptionReporterFilter.

  • The cache timeout set by cache_page() decorator now takes precedence over the max-age directive from the Cache-Control header.

  • Providing a non-local remote field in the ForeignKey.to_field argument now raises FieldError.

  • SECURE_REFERRER_POLICY now defaults to 'same-origin'. See the What’s New Security section above for more details.

  • check management command now runs the database system checks only for database aliases specified using check --database option.

  • migrate management command now runs the database system checks only for a database to migrate.

  • The admin CSS classes row1 and row2 are removed in favor of :nth-child(odd) and :nth-child(even) pseudo-classes.

  • The make_password() function now requires its argument to be a string or bytes. Other types should be explicitly cast to one of these.

  • The undocumented version parameter to the AsKML function is removed.

  • JSON and YAML serializers, used by dumpdata, now dump all data with Unicode by default. If you need the previous behavior, pass ensure_ascii=True to JSON serializer, or allow_unicode=False to YAML serializer.

  • The auto-reloader no longer monitors changes in built-in Django translation files.

  • The minimum supported version of mysqlclient is increased from 1.3.13 to 1.4.0.

  • The undocumented django.contrib.postgres.forms.InvalidJSONInput and django.contrib.postgres.forms.JSONString are moved to django.forms.fields.

  • The undocumented django.contrib.postgres.fields.jsonb.JsonAdapter class is removed.

  • The {% localize off %} tag and unlocalize filter no longer respect DECIMAL_SEPARATOR setting.

  • The minimum supported version of asgiref is increased from 3.2 to 3.2.10.

  • The Media class now renders <script> tags without the type attribute to follow WHATWG recommendations.

  • ModelChoiceIterator, used by ModelChoiceField and ModelMultipleChoiceField, now yields 2-tuple choices containing ModelChoiceIteratorValue instances as the first value element in each choice. In most cases this proxies transparently, but if you need the field value itself, use the ModelChoiceIteratorValue.value attribute instead.

Features deprecated in 3.1

PostgreSQL JSONField

django.contrib.postgres.fields.JSONField and django.contrib.postgres.forms.JSONField are deprecated in favor of models.JSONField and forms.JSONField.

The undocumented django.contrib.postgres.fields.jsonb.KeyTransform and django.contrib.postgres.fields.jsonb.KeyTextTransform are also deprecated in favor of the transforms in django.db.models.fields.json.

The new JSONFields, KeyTransform, and KeyTextTransform can be used on all supported database backends.

Miscellaneous

  • PASSWORD_RESET_TIMEOUT_DAYS setting is deprecated in favor of PASSWORD_RESET_TIMEOUT.

  • The undocumented usage of the isnull lookup with non-boolean values as the right-hand side is deprecated, use True or False instead.

  • The barely documented django.db.models.query_utils.InvalidQuery exception class is deprecated in favor of FieldDoesNotExist and FieldError.

  • The django-admin.py entry point is deprecated in favor of django-admin.

  • The HttpRequest.is_ajax() method is deprecated as it relied on a jQuery-specific way of signifying AJAX calls, while current usage tends to use the JavaScript Fetch API. Depending on your use case, you can either write your own AJAX detection method, or use the new HttpRequest.accepts() method if your code depends on the client Accept HTTP header.

    If you are writing your own AJAX detection method, request.is_ajax() can be reproduced exactly as request.headers.get('x-requested-with') == 'XMLHttpRequest'.

  • Passing None as the first argument to django.utils.deprecation.MiddlewareMixin.__init__() is deprecated.

  • The encoding format of cookies values used by CookieStorage is different from the format generated by older versions of Django. Support for the old format remains until Django 4.0.

  • The encoding format of sessions is different from the format generated by older versions of Django. Support for the old format remains until Django 4.0.

  • The purely documentational providing_args argument for Signal is deprecated. If you rely on this argument as documentation, you can move the text to a code comment or docstring.

  • Calling django.utils.crypto.get_random_string() without a length argument is deprecated.

  • The list message for ModelMultipleChoiceField is deprecated in favor of invalid_list.

  • Passing raw column aliases to QuerySet.order_by() is deprecated. The same result can be achieved by passing aliases in a RawSQL instead beforehand.

  • The NullBooleanField model field is deprecated in favor of BooleanField(null=True).

  • django.conf.urls.url() alias of django.urls.re_path() is deprecated.

  • The {% ifequal %} and {% ifnotequal %} template tags are deprecated in favor of {% if %}. {% if %} covers all use cases, but if you need to continue using these tags, they can be extracted from Django to a module and included as a built-in tag in the 'builtins' option in OPTIONS.

  • DEFAULT_HASHING_ALGORITHM transitional setting is deprecated.

Features removed in 3.1

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

See Features deprecated in 2.2 for details on these changes, including how to remove usage of these features.

  • django.utils.timezone.FixedOffset is removed.

  • django.core.paginator.QuerySetPaginator is removed.

  • A model’s Meta.ordering doesn’t affect GROUP BY queries.

  • django.contrib.postgres.fields.FloatRangeField and django.contrib.postgres.forms.FloatRangeField are removed.

  • The FILE_CHARSET setting is removed.

  • django.contrib.staticfiles.storage.CachedStaticFilesStorage is removed.

  • The RemoteUserBackend.configure_user() method requires request as the first positional argument.

  • Support for SimpleTestCase.allow_database_queries and TransactionTestCase.multi_db is removed.

« previous | up | next »