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

\n

December 7, 2021

\n

Welcome to Django 4.0!

\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.2 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.0 supports Python 3.8, 3.9, and 3.10. We highly recommend and only\nofficially support the latest release of each series.

\n

The Django 3.2.x series is the last to support Python 3.6 and 3.7.

\n
\n
\n

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

\n
\n

zoneinfo default timezone implementationLink to this heading#

\n

The Python standard library’s zoneinfo is now the default timezone\nimplementation in Django.

\n

This is the next step in the migration from using pytz to using\nzoneinfo. Django 3.2 allowed the use of non-pytz time zones. Django\n4.0 makes zoneinfo the default implementation. Support for pytz is now\ndeprecated and will be removed in Django 5.0.

\n

zoneinfo is part of the Python standard library from Python 3.9. The\nbackports.zoneinfo package is automatically installed alongside Django if\nyou are using Python 3.8.

\n

The move to zoneinfo should be largely transparent. Selection of the\ncurrent timezone, conversion of datetime instances to the current timezone in\nforms and templates, as well as operations on aware datetimes in UTC are\nunaffected.

\n

However, if you are working with non-UTC time zones, and using the pytz\nnormalize() and localize() APIs, possibly with the TIME_ZONE setting, you will need to audit your code, since pytz\nand zoneinfo are not entirely equivalent.

\n

To give time for such an audit, the transitional USE_DEPRECATED_PYTZ\nsetting allows continued use of pytz during the 4.x release cycle. This\nsetting will be removed in Django 5.0.

\n

In addition, a pytz_deprecation_shim package, created by the zoneinfo\nauthor, can be used to assist with the migration from pytz. This package\nprovides shims to help you safely remove pytz, and has a detailed\nmigration guide showing how to move to the new zoneinfo APIs.

\n

Using pytz_deprecation_shim and the USE_DEPRECATED_PYTZ\ntransitional setting is recommended if you need a gradual update path.

\n
\n
\n

Functional unique constraintsLink to this heading#

\n

The new *expressions\npositional argument of\nUniqueConstraint() enables\ncreating functional unique constraints on expressions and database functions.\nFor example:

\n
Code
from django.db import models\nfrom django.db.models import UniqueConstraint\nfrom django.db.models.functions import Lower\n\n\nclass MyModel(models.Model):\n    first_name = models.CharField(max_length=255)\n    last_name = models.CharField(max_length=255)\n\n    class Meta:\n        constraints = [\n            UniqueConstraint(\n                Lower("first_name"),\n                Lower("last_name").desc(),\n                name="first_last_name_unique",\n            ),\n        ]\n
\n

Functional unique constraints are added to models using the\nMeta.constraints option.

\n
\n
\n

scrypt password hasherLink to this heading#

\n

The new scrypt password hasher is more secure and\nrecommended over PBKDF2. However, it’s not the default as it requires OpenSSL\n1.1+ and more memory.

\n
\n
\n

Redis cache backendLink to this heading#

\n

The new django.core.cache.backends.redis.RedisCache cache backend provides\nbuilt-in support for caching with Redis. redis-py 3.0.0 or\nhigher is required. For more details, see the documentation on caching\nwith Redis in Django.

\n
\n
\n

Template based form renderingLink to this heading#

\n

Forms, Formsets,\nand ErrorList are now rendered using the template engine\nto enhance customization. See the new render(),\nget_context(), and\ntemplate_name for Form and\nformset rendering for Formset.

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n\n
\n
\n

django.contrib.admindocsLink to this heading#

\n
    \n

  • The admindocs now allows esoteric setups where ROOT_URLCONF is not\na string.

    • \n

  • The model section of the admindocs now shows cached properties.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n
    \n

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

    • \n

  • The new\nLoginView.next_page\nattribute and\nget_default_redirect_url() method\nallow customizing the redirect after login.

    • \n
\n
\n
\n

django.contrib.gisLink to this heading#

\n
    \n

  • Added support for SpatiaLite 5.

    • \n

  • GDALRaster now allows creating rasters in\nany GDAL virtual filesystem.

    • \n

  • The new GISModelAdmin class allows\ncustomizing the widget used for GeometryField. This is encouraged instead\nof deprecated GeoModelAdmin and OSMGeoAdmin.

    • \n
\n
\n
\n

django.contrib.postgresLink to this heading#

\n\n
\n
\n

django.contrib.staticfilesLink to this heading#

\n\n
\n
\n

CacheLink to this heading#

\n
    \n

  • The new async API for django.core.cache.backends.base.BaseCache begins\nthe process of making cache backends async-compatible. The new async methods\nall have a prefixed names, e.g. aadd(), aget(), aset(),\naget_or_set(), or adelete_many().

    \n

    Going forward, the a prefix will be used for async variants of methods\ngenerally.

    \n
    • \n
\n
\n
\n

CSRFLink to this heading#

\n\n
\n
\n

FormsLink to this heading#

\n
    \n

  • ModelChoiceField now includes the provided value in\nthe params argument of a raised\nValidationError for the invalid_choice\nerror message. This allows custom error messages to use the %(value)s\nplaceholder.

    • \n

  • BaseFormSet now renders non-form errors with\nan additional class of nonform to help distinguish them from\nform-specific errors.

    • \n

  • BaseFormSet now allows customizing the widget\nused when deleting forms via\ncan_delete by setting the\ndeletion_widget attribute or\noverriding get_deletion_widget()\nmethod.

    • \n
\n
\n
\n

InternationalizationLink to this heading#

\n
    \n

  • Added support and translations for the Malay language.

    • \n
\n
\n
\n

Generic ViewsLink to this heading#

\n
    \n

  • DeleteView now uses\nFormMixin, allowing you to provide a\nForm subclass, with a checkbox for example, to confirm\ndeletion. In addition, this allows DeleteView to function with\ndjango.contrib.messages.views.SuccessMessageMixin.

    \n

    In accordance with FormMixin, object deletion for POST requests is\nhandled in form_valid(). Custom delete logic in delete() handlers\nshould be moved to form_valid(), or a shared helper method, as needed.

    \n
    • \n
\n
\n
\n

LoggingLink to this heading#

\n
    \n

  • The alias of the database used in an SQL call is now passed as extra context\nalong with each message to the django.db.backends logger.

    • \n
\n
\n
\n

Management CommandsLink to this heading#

\n\n
\n
\n

ModelsLink to this heading#

\n
    \n

  • New QuerySet.contains(obj) method returns\nwhether the queryset contains the given object. This tries to perform the\nquery in the simplest and fastest way possible.

    • \n

  • The new precision argument of the\nRound() database function allows\nspecifying the number of decimal places after rounding.

    • \n

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

    • \n

  • DurationField now supports multiplying and\ndividing by scalar values on SQLite.

    • \n

  • QuerySet.bulk_update() now returns the number of objects updated.

    • \n

  • The new Expression.empty_result_set_value attribute allows\nspecifying a value to return when the function is used over an empty result\nset.

    • \n

  • The skip_locked argument of QuerySet.select_for_update() is now\nallowed on MariaDB 10.6+.

    • \n

  • Lookup expressions may now be used in QuerySet\nannotations, aggregations, and directly in filters.

    • \n

  • The new default argument for built-in aggregates\nallows specifying a value to be returned when the queryset (or grouping)\ncontains no entries, rather than None.

    • \n
\n
\n
\n

Requests and ResponsesLink to this heading#

\n\n
\n
\n

SignalsLink to this heading#

\n
    \n

  • The new stdout argument for pre_migrate()\nand post_migrate() signals allows redirecting\noutput to a stream-like object. It should be preferred over\nsys.stdout and print() when emitting verbose output in\norder to allow proper capture when testing.

    • \n
\n
\n
\n

TemplatesLink to this heading#

\n
    \n

  • floatformat template filter now allows using the u suffix to\nforce disabling localization.

    • \n
\n
\n
\n

TestsLink to this heading#

\n\n
\n
\n
\n
\n

Backwards incompatible changes in 4.0Link 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 9.6Link to this heading#

\n

Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports\nPostgreSQL 10 and higher.

\n

Also, the minimum supported version of psycopg2 is increased from 2.5.4 to\n2.8.4, as psycopg2 2.8.4 is the first release to support Python 3.8.

\n
\n
\n

Dropped support for Oracle 12.2 and 18cLink to this heading#

\n

Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends\nin June 2021. Django 3.2 will be supported until April 2024. Django 4.0\nofficially supports Oracle 19c.

\n
\n
\n

CSRF_TRUSTED_ORIGINS changesLink to this heading#

\n
\n

Format changeLink to this heading#

\n

Values in the CSRF_TRUSTED_ORIGINS setting must include the scheme\n(e.g. 'http://' or 'https://') instead of only the hostname.

\n

Also, values that started with a dot, must now also include an asterisk before\nthe dot. For example, change '.example.com' to 'https://*.example.com'.

\n

A system check detects any required changes.

\n
\n
\n

Configuring it may now be requiredLink to this heading#

\n

As CSRF protection now consults the Origin header, you may need to set\nCSRF_TRUSTED_ORIGINS, particularly if you allow requests from\nsubdomains by setting CSRF_COOKIE_DOMAIN (or\nSESSION_COOKIE_DOMAIN if CSRF_USE_SESSIONS is enabled) to\na value starting with a dot.

\n
\n
\n
\n

SecurityMiddleware no longer sets the X-XSS-Protection headerLink to this heading#

\n

The SecurityMiddleware no longer sets the\nX-XSS-Protection header if the SECURE_BROWSER_XSS_FILTER setting is\nTrue. The setting is removed.

\n

Most modern browsers don’t honor the X-XSS-Protection HTTP header. You can\nuse Content-Security-Policy without allowing 'unsafe-inline' scripts\ninstead.

\n

If you want to support legacy browsers and set the header, use this line in a\ncustom middleware:

\n
Code
response.headers.setdefault("X-XSS-Protection", "1; mode=block")\n
\n
\n
\n

Migrations autodetector changesLink to this heading#

\n

The migrations autodetector now uses model states instead of model classes.\nAlso, migration operations for ForeignKey and ManyToManyField fields no\nlonger specify attributes which were not passed to the fields during\ninitialization.

\n

As a side-effect, running makemigrations might generate no-op\nAlterField operations for ManyToManyField and ForeignKey fields in\nsome cases.

\n
\n
\n

DeleteView changesLink to this heading#

\n

DeleteView now uses\nFormMixin to handle POST requests. As a\nconsequence, any custom deletion logic in delete() handlers should be\nmoved to form_valid(), or a shared helper method, if required.

\n
\n
\n

Table and column naming scheme changes on OracleLink to this heading#

\n

Django 4.0 inadvertently changed the table and column naming scheme on Oracle.\nThis causes errors for models and fields with names longer than 30 characters.\nUnfortunately, renaming some Oracle tables and columns is required. Use the\nupgrade script in 33789 to generate RENAME\nstatements to change naming scheme.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 4.0Link to this heading#

\n
\n

Use of pytz time zonesLink to this heading#

\n

As part of the move to zoneinfo, use of pytz time\nzones is deprecated.

\n

Accordingly, the is_dst arguments to the following are also deprecated:

\n\n

Support for use of pytz will be removed in Django 5.0.

\n
\n
\n

Time zone supportLink to this heading#

\n

In order to follow good practice, the default value of the USE_TZ\nsetting will change from False to True, and time zone support will be\nenabled by default, in Django 5.0.

\n

Note that the default settings.py file created by\ndjango-admin startproject includes\nUSE_TZ = True since Django 1.4.

\n

You can set USE_TZ to False in your project settings before then to\nopt-out.

\n
\n
\n

LocalizationLink to this heading#

\n

In order to follow good practice, the default value of the USE_L10N setting\nis changed from False to True.

\n

Moreover USE_L10N is deprecated as of this release. Starting with Django\n5.0, by default, any date or number displayed by Django will be localized.

\n

The {% localize %} tag and the localize/\nunlocalize filters will still be honored by Django.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features removed in 4.0Link to this heading#

\n

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

\n

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

\n\n

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

\n\n
","rootId":"django-4-0-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 4.0","anchor":"what-s-new-in-django-4-0","children":[{"title":"zoneinfo default timezone implementation","anchor":"zoneinfo-default-timezone-implementation","children":[]},{"title":"Functional unique constraints","anchor":"functional-unique-constraints","children":[]},{"title":"scrypt password hasher","anchor":"scrypt-password-hasher","children":[]},{"title":"Redis cache backend","anchor":"redis-cache-backend","children":[]},{"title":"Template based form rendering","anchor":"template-based-form-rendering","children":[]},{"title":"Minor features","anchor":"minor-features","children":[{"title":"django.contrib.admin","anchor":"django-contrib-admin","children":[]},{"title":"django.contrib.admindocs","anchor":"django-contrib-admindocs","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.staticfiles","anchor":"django-contrib-staticfiles","children":[]},{"title":"Cache","anchor":"cache","children":[]},{"title":"CSRF","anchor":"csrf","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Internationalization","anchor":"internationalization","children":[]},{"title":"Generic Views","anchor":"generic-views","children":[]},{"title":"Logging","anchor":"logging","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Signals","anchor":"signals","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]}]}]},{"title":"Backwards incompatible changes in 4.0","anchor":"backwards-incompatible-changes-in-4-0","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.gis","anchor":"id1","children":[]},{"title":"Dropped support for PostgreSQL 9.6","anchor":"dropped-support-for-postgresql-9-6","children":[]},{"title":"Dropped support for Oracle 12.2 and 18c","anchor":"dropped-support-for-oracle-12-2-and-18c","children":[]},{"title":"CSRF_TRUSTED_ORIGINS changes","anchor":"csrf-trusted-origins-changes","children":[{"title":"Format change","anchor":"format-change","children":[]},{"title":"Configuring it may now be required","anchor":"configuring-it-may-now-be-required","children":[]}]},{"title":"SecurityMiddleware no longer sets the X-XSS-Protection header","anchor":"securitymiddleware-no-longer-sets-the-x-xss-protection-header","children":[]},{"title":"Migrations autodetector changes","anchor":"migrations-autodetector-changes","children":[]},{"title":"DeleteView changes","anchor":"deleteview-changes","children":[]},{"title":"Table and column naming scheme changes on Oracle","anchor":"table-and-column-naming-scheme-changes-on-oracle","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 4.0","anchor":"features-deprecated-in-4-0","children":[{"title":"Use of pytz time zones","anchor":"use-of-pytz-time-zones","children":[]},{"title":"Time zone support","anchor":"time-zone-support","children":[]},{"title":"Localization","anchor":"localization","children":[]},{"title":"Miscellaneous","anchor":"id2","children":[]}]},{"title":"Features removed in 4.0","anchor":"features-removed-in-4-0","children":[]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/4.0.1","title":"Django 4.0.1 release notes","url":"/en/dev/releases/4.0.1/"},"next":{"docname":"releases/3.2.25","title":"Django 3.2.25 release notes","url":"/en/dev/releases/3.2.25/"},"formats":{"html":"/en/dev/releases/4.0/","markdown":"/en/dev/releases/4.0.md","json":"/en/dev/releases/4.0.json"},"source":"https://github.com/django/django/blob/main/docs/releases/4.0.txt","official":"https://docs.djangoproject.com/en/dev/releases/4.0/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0"],"inLocales":["en"]}