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

Django 3.1 release notesLink to this heading#

\n

August 4, 2020

\n

Welcome to Django 3.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 3.0 or earlier. We’ve\ndropped some features that have reached the end of\ntheir deprecation cycle, and we’ve begun the deprecation process for\nsome 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 3.1 supports Python 3.6, 3.7, 3.8, and 3.9 (as of 3.1.3). We highly\nrecommend and only officially support the latest release of each series.

\n
\n
\n

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

\n
\n

Asynchronous views and middleware supportLink to this heading#

\n

Django now supports a fully asynchronous request path, including:

\n\n

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

\n
Code
async def my_view(request):\n    await asyncio.sleep(0.5)\n    return HttpResponse("Hello, async world!")\n
\n

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

\n

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

\n

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

\n

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

\n
\n
\n

JSONField for all supported database backendsLink to this heading#

\n

Django now includes models.JSONField and\nforms.JSONField that can be used on all\nsupported database backends. Both fields support the use of custom JSON\nencoders and decoders. The model field supports the introspection,\nlookups, and transforms that were previously\nPostgreSQL-only:

\n
Code
from django.db import models\n\n\nclass ContactInfo(models.Model):\n    data = models.JSONField()\n\n\nContactInfo.objects.create(\n    data={\n        "name": "John",\n        "cities": ["London", "Cambridge"],\n        "pets": {"dogs": ["Rufus", "Meg"]},\n    }\n)\nContactInfo.objects.filter(\n    data__name="John",\n    data__pets__has_key="dogs",\n    data__cities__contains="London",\n).delete()\n
\n

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

\n
\n
\n

DEFAULT_HASHING_ALGORITHM settingsLink to this heading#

\n

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

\n

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

\n

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

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

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

    • \n

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

    • \n

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

    \n

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

    \n
    • \n

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

    • \n

  • XRegExp is upgraded from version 2.0.0 to 3.2.0.

    • \n

  • jQuery is upgraded from version 3.4.1 to 3.5.1.

    • \n

  • Select2 library is upgraded from version 4.0.7 to 4.0.13.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n
    \n

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

    • \n

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

    • \n

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

    • \n

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

    • \n
\n
\n
\n

django.contrib.contenttypesLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

django.contrib.humanizeLink to this heading#

\n
    \n

  • intword template filter now supports negative integers.

    • \n
\n
\n
\n

django.contrib.postgresLink to this heading#

\n\n
\n
\n

django.contrib.sessionsLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

django.contrib.staticfilesLink to this heading#

\n\n
\n
\n

CacheLink to this heading#

\n\n
\n
\n

CSRFLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

EmailLink to this heading#

\n\n
\n
\n

Error ReportingLink to this heading#

\n\n
\n
\n

File StorageLink to this heading#

\n
    \n

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

    • \n

  • FileField and\nImageField now accept a callable for storage.\nThis allows you to modify the used storage at runtime, selecting different\nstorages for different environments, for example.

    • \n
\n
\n
\n

FormsLink to this heading#

\n\n
\n
\n

InternationalizationLink to this heading#

\n
    \n

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

    • \n

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

    • \n
\n
\n
\n

Management CommandsLink to this heading#

\n
    \n

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

    • \n

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

    • \n

  • The new returncode argument for\nCommandError allows customizing the exit\nstatus for management commands.

    • \n

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

    • \n

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

    • \n
\n
\n
\n

ModelsLink to this heading#

\n
    \n

  • The new ExtractIsoWeekDay function\nextracts ISO-8601 week days from DateField and\nDateTimeField, and the new iso_week_day\nlookup allows querying by an ISO-8601 day of week.

    • \n

  • QuerySet.explain() now supports:

    \n
      \n

    • TREE format on MySQL 8.0.16+,

      • \n

    • analyze option on MySQL 8.0.18+ and MariaDB.

      • \n
    \n
    • \n

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

    • \n

  • The new RESTRICT option for\non_delete argument of ForeignKey and\nOneToOneField emulates the behavior of the SQL constraint ON DELETE\nRESTRICT.

    • \n

  • CheckConstraint.check now supports boolean expressions.

    • \n

  • The RelatedManager.add(), create(), and\nset() methods now accept callables as values in the\nthrough_defaults argument.

    • \n

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

    • \n

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

    • \n

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

    • \n

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

    • \n

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

    • \n

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

    • \n
\n
\n
\n

PaginationLink to this heading#

\n
    \n

  • Paginator can now be iterated over to yield\nits pages.

    • \n
\n
\n
\n

Requests and ResponsesLink to this heading#

\n
    \n

  • If ALLOWED_HOSTS is empty and DEBUG=True, subdomains of\nlocalhost are now allowed in the Host header, e.g. static.localhost.

    • \n

  • HttpResponse.set_cookie() and HttpResponse.set_signed_cookie()\nnow allow using samesite='None' (string) to explicitly state that the\ncookie is sent with all same-site and cross-site requests.

    • \n

  • The new HttpRequest.accepts() method returns whether the request\naccepts the given MIME type according to the Accept HTTP header.

    • \n
\n
\n
\n

SecurityLink to this heading#

\n\n
\n
\n

TemplatesLink to this heading#

\n
    \n

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

    • \n

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

    • \n
\n
\n
\n

TestsLink to this heading#

\n
    \n

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

    • \n

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

    • \n

  • DiscoverRunner can now discard output for\npassing tests using the test --buffer option.

    • \n

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

    • \n

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

    • \n
\n
\n
\n

URLsLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

UtilitiesLink to this heading#

\n\n
\n
\n

MiscellaneousLink to this heading#

\n
    \n

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

    • \n

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

    • \n

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

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

Backwards incompatible changes in 3.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

Dropped support for MariaDB 10.1Link to this heading#

\n

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

\n
\n
\n

contrib.admin browser supportLink to this heading#

\n

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

\n
\n
\n

AbstractUser.first_name max_length increased to 150Link to this heading#

\n

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

\n

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

\n
Code
from django import forms\nfrom django.contrib.auth.forms import UserChangeForm\n\n\nclass MyUserChangeForm(UserChangeForm):\n    first_name = forms.CharField(max_length=30, required=False)\n
\n

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

\n
Code
from django.contrib.auth.admin import UserAdmin\nfrom django.contrib.auth.models import User\n\n\nclass MyUserAdmin(UserAdmin):\n    form = MyUserChangeForm\n\n\nadmin.site.unregister(User)\nadmin.site.register(User, MyUserAdmin)\n
\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 3.1Link to this heading#

\n
\n

PostgreSQL JSONFieldLink to this heading#

\n

django.contrib.postgres.fields.JSONField and\ndjango.contrib.postgres.forms.JSONField are deprecated in favor of\nmodels.JSONField and\nforms.JSONField.

\n

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

\n

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

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features removed in 3.1Link to this heading#

\n

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

\n

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

\n\n
","rootId":"django-3-1-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 3.1","anchor":"what-s-new-in-django-3-1","children":[{"title":"Asynchronous views and middleware support","anchor":"asynchronous-views-and-middleware-support","children":[]},{"title":"JSONField for all supported database backends","anchor":"jsonfield-for-all-supported-database-backends","children":[]},{"title":"DEFAULT_HASHING_ALGORITHM settings","anchor":"default-hashing-algorithm-settings","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.contenttypes","anchor":"django-contrib-contenttypes","children":[]},{"title":"django.contrib.gis","anchor":"django-contrib-gis","children":[]},{"title":"django.contrib.humanize","anchor":"django-contrib-humanize","children":[]},{"title":"django.contrib.postgres","anchor":"django-contrib-postgres","children":[]},{"title":"django.contrib.sessions","anchor":"django-contrib-sessions","children":[]},{"title":"django.contrib.staticfiles","anchor":"django-contrib-staticfiles","children":[]},{"title":"Cache","anchor":"cache","children":[]},{"title":"CSRF","anchor":"csrf","children":[]},{"title":"Email","anchor":"email","children":[]},{"title":"Error Reporting","anchor":"error-reporting","children":[]},{"title":"File Storage","anchor":"file-storage","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Internationalization","anchor":"internationalization","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Pagination","anchor":"pagination","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Security","anchor":"security","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"URLs","anchor":"urls","children":[]},{"title":"Utilities","anchor":"utilities","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]}]},{"title":"Backwards incompatible changes in 3.1","anchor":"backwards-incompatible-changes-in-3-1","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"Dropped support for MariaDB 10.1","anchor":"dropped-support-for-mariadb-10-1","children":[]},{"title":"contrib.admin browser support","anchor":"contrib-admin-browser-support","children":[]},{"title":"AbstractUser.first_name max_length increased to 150","anchor":"abstractuser-first-name-max-length-increased-to-150","children":[]},{"title":"Miscellaneous","anchor":"id1","children":[]}]},{"title":"Features deprecated in 3.1","anchor":"features-deprecated-in-3-1","children":[{"title":"PostgreSQL JSONField","anchor":"postgresql-jsonfield","children":[]},{"title":"Miscellaneous","anchor":"id2","children":[]}]},{"title":"Features removed in 3.1","anchor":"features-removed-in-3-1","children":[]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/3.1.1","title":"Django 3.1.1 release notes","url":"/en/dev/releases/3.1.1/"},"next":{"docname":"releases/3.0.14","title":"Django 3.0.14 release notes","url":"/en/dev/releases/3.0.14/"},"formats":{"html":"/en/dev/releases/3.1/","markdown":"/en/dev/releases/3.1.md","json":"/en/dev/releases/3.1.json"},"source":"https://github.com/django/django/blob/main/docs/releases/3.1.txt","official":"https://docs.djangoproject.com/en/dev/releases/3.1/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1"],"inLocales":["en"]}