Django 3.1 release notes - UNDER DEVELOPMENT

Expected August 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, and 3.8. We highly recommend and only officially support the latest release of each series.

What’s new in Django 3.1

Minor features


  • 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 contains a link to clear all filters.


  • The default iteration count for the PBKDF2 password hasher is increased from 180,000 to 216,000.
  • Added the PASSWORD_RESET_TIMEOUT setting to define the minimum number of seconds a password reset link is valid for. This is encouraged instead of deprecated PASSWORD_RESET_TIMEOUT_DAYS, 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.




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



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


Error Reporting

File Storage

  • method now supports pathlib.Path.

File Uploads


Generic Views


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


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.


  • Migrations are now loaded also from directories without files.


Requests and Responses





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


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


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




  • The SQLite backend now supports pathlib.Path for the NAME setting.
  • The 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.

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.


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

Features deprecated in 3.1


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

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