Django 4.0 release notes¶
December 7, 2021
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 from Django 3.2 or earlier. We’ve begun the deprecation process for some features.
See the How to upgrade Django to a newer version guide if you’re updating an existing project.
Python compatibility¶
Django 4.0 supports Python 3.8, 3.9, and 3.10. We highly recommend and only officially support the latest release of each series.
The Django 3.2.x series is the last to support Python 3.6 and 3.7.
What’s new in Django 4.0¶
zoneinfo
default timezone implementation¶
The Python standard library’s zoneinfo
is now the default timezone
implementation in Django.
This is the next step in the migration from using pytz
to using
zoneinfo
. Django 3.2 allowed the use of non-pytz
time zones. Django
4.0 makes zoneinfo
the default implementation. Support for pytz
is now
deprecated and will be removed in Django 5.0.
zoneinfo
is part of the Python standard library from Python 3.9. The
backports.zoneinfo
package is automatically installed alongside Django if
you are using Python 3.8.
The move to zoneinfo
should be largely transparent. Selection of the
current timezone, conversion of datetime instances to the current timezone in
forms and templates, as well as operations on aware datetimes in UTC are
unaffected.
However, if you are working with non-UTC time zones, and using the pytz
normalize()
and localize()
APIs, possibly with the TIME_ZONE
setting, you will need to audit your code, since pytz
and zoneinfo
are not entirely equivalent.
To give time for such an audit, the transitional USE_DEPRECATED_PYTZ
setting allows continued use of pytz
during the 4.x release cycle. This
setting will be removed in Django 5.0.
In addition, a pytz_deprecation_shim package, created by the zoneinfo
author, can be used to assist with the migration from pytz
. This package
provides shims to help you safely remove pytz
, and has a detailed
migration guide showing how to move to the new zoneinfo
APIs.
Using pytz_deprecation_shim and the USE_DEPRECATED_PYTZ
transitional setting is recommended if you need a gradual update path.
Functional unique constraints¶
The new *expressions
positional argument of
UniqueConstraint()
enables
creating functional unique constraints on expressions and database functions.
For example:
from django.db import models
from django.db.models import UniqueConstraint
from django.db.models.functions import Lower
class MyModel(models.Model):
first_name = models.CharField(max_length=255)
last_name = models.CharField(max_length=255)
class Meta:
constraints = [
UniqueConstraint(
Lower("first_name"),
Lower("last_name").desc(),
name="first_last_name_unique",
),
]
Functional unique constraints are added to models using the
Meta.constraints
option.
scrypt
password hasher¶
The new scrypt password hasher is more secure and recommended over PBKDF2. However, it’s not the default as it requires OpenSSL 1.1+ and more memory.
Redis cache backend¶
The new django.core.cache.backends.redis.RedisCache
cache backend provides
built-in support for caching with Redis. redis-py 3.0.0 or
higher is required. For more details, see the documentation on caching
with Redis in Django.
Template based form rendering¶
Forms
, Formsets,
and ErrorList
are now rendered using the template engine
to enhance customization. See the new render()
,
get_context()
, and
template_name
for Form
and
formset rendering for Formset
.
Minor features¶
django.contrib.admin
¶
The
admin/base.html
template now has a new blockheader
which contains the admin site header.The new
ModelAdmin.get_formset_kwargs()
method allows customizing the keyword arguments passed to the constructor of a formset.The navigation sidebar now has a quick filter toolbar.
The new context variable
model
which contains the model class for each model is added to theAdminSite.each_context()
method.The new
ModelAdmin.search_help_text
attribute allows specifying a descriptive text for the search box.The
InlineModelAdmin.verbose_name_plural
attribute now fallbacks to theInlineModelAdmin.verbose_name
+'s'
.jQuery is upgraded from version 3.5.1 to 3.6.0.
django.contrib.admindocs
¶
The admindocs now allows esoteric setups where
ROOT_URLCONF
is not a string.The model section of the
admindocs
now shows cached properties.
django.contrib.auth
¶
The default iteration count for the PBKDF2 password hasher is increased from 260,000 to 320,000.
The new
LoginView.next_page
attribute andget_default_redirect_url()
method allow customizing the redirect after login.
django.contrib.gis
¶
Added support for SpatiaLite 5.
GDALRaster
now allows creating rasters in any GDAL virtual filesystem.The new
GISModelAdmin
class allows customizing the widget used forGeometryField
. This is encouraged instead of deprecatedGeoModelAdmin
andOSMGeoAdmin
.
django.contrib.postgres
¶
The PostgreSQL backend now supports connecting by a service name. See PostgreSQL connection settings for more details.
The new
AddConstraintNotValid
operation allows creating check constraints on PostgreSQL without verifying that all existing rows satisfy the new constraint.The new
ValidateConstraint
operation allows validating check constraints which were created usingAddConstraintNotValid
on PostgreSQL.The new
ArraySubquery()
expression allows using subqueries to construct lists of values on PostgreSQL.The new
trigram_word_similar
lookup, and theTrigramWordDistance()
andTrigramWordSimilarity()
expressions allow using trigram word similarity.
django.contrib.staticfiles
¶
ManifestStaticFilesStorage
now replaces paths to JavaScript source map references with their hashed counterparts.The new
manifest_storage
argument ofManifestFilesMixin
andManifestStaticFilesStorage
allows customizing the manifest file storage.
Cache¶
The new async API for
django.core.cache.backends.base.BaseCache
begins the process of making cache backends async-compatible. The new async methods all havea
prefixed names, e.g.aadd()
,aget()
,aset()
,aget_or_set()
, oradelete_many()
.Going forward, the
a
prefix will be used for async variants of methods generally.
CSRF¶
CSRF protection now consults the
Origin
header, if present. To facilitate this, some changes to theCSRF_TRUSTED_ORIGINS
setting are required.
Forms¶
ModelChoiceField
now includes the provided value in theparams
argument of a raisedValidationError
for theinvalid_choice
error message. This allows custom error messages to use the%(value)s
placeholder.BaseFormSet
now renders non-form errors with an additional class ofnonform
to help distinguish them from form-specific errors.BaseFormSet
now allows customizing the widget used when deleting forms viacan_delete
by setting thedeletion_widget
attribute or overridingget_deletion_widget()
method.
Internationalization¶
Added support and translations for the Malay language.
Generic Views¶
DeleteView
now usesFormMixin
, allowing you to provide aForm
subclass, with a checkbox for example, to confirm deletion. In addition, this allowsDeleteView
to function withdjango.contrib.messages.views.SuccessMessageMixin
.In accordance with
FormMixin
, object deletion for POST requests is handled inform_valid()
. Custom delete logic indelete()
handlers should be moved toform_valid()
, or a shared helper method, as needed.
Logging¶
The alias of the database used in an SQL call is now passed as extra context along with each message to the django.db.backends logger.
Management Commands¶
The
runserver
management command now supports the--skip-checks
option.On PostgreSQL,
dbshell
now supports specifying a password file.The
shell
command now respectssys.__interactivehook__
at startup. This allows loading shell history between interactive sessions. As a consequence,readline
is no longer loaded if running in isolated mode.The new
BaseCommand.suppressed_base_arguments
attribute allows suppressing unsupported default command options in the help output.The new
startapp --exclude
andstartproject --exclude
options allow excluding directories from the template.
Models¶
New
QuerySet.contains(obj)
method returns whether the queryset contains the given object. This tries to perform the query in the simplest and fastest way possible.The new
precision
argument of theRound()
database function allows specifying the number of decimal places after rounding.QuerySet.bulk_create()
now sets the primary key on objects when using SQLite 3.35+.DurationField
now supports multiplying and dividing by scalar values on SQLite.QuerySet.bulk_update()
now returns the number of objects updated.The new
Expression.empty_result_set_value
attribute allows specifying a value to return when the function is used over an empty result set.The
skip_locked
argument ofQuerySet.select_for_update()
is now allowed on MariaDB 10.6+.Lookup
expressions may now be used inQuerySet
annotations, aggregations, and directly in filters.The new default argument for built-in aggregates allows specifying a value to be returned when the queryset (or grouping) contains no entries, rather than
None
.
Requests and Responses¶
The
SecurityMiddleware
now adds the Cross-Origin Opener Policy header with a value of'same-origin'
to prevent cross-origin popups from sharing the same browsing context. You can prevent this header from being added by setting theSECURE_CROSS_ORIGIN_OPENER_POLICY
setting toNone
.
Signals¶
The new
stdout
argument forpre_migrate()
andpost_migrate()
signals allows redirecting output to a stream-like object. It should be preferred oversys.stdout
andprint()
when emitting verbose output in order to allow proper capture when testing.
Templates¶
floatformat
template filter now allows using theu
suffix to force disabling localization.
Tests¶
The new
serialized_aliases
argument ofdjango.test.utils.setup_databases()
determines whichDATABASES
aliases test databases should have their state serialized to allow usage of the serialized_rollback feature.Django test runner now supports a
--buffer
option with parallel tests.The new
logger
argument toDiscoverRunner
allows a Python logger to be used for logging.The new
DiscoverRunner.log()
method provides a way to log messages that uses theDiscoverRunner.logger
, or prints to the console if not set.Django test runner now supports a
--shuffle
option to execute tests in a random order.The
test --parallel
option now supports the valueauto
to run one test process for each processor core.TestCase.captureOnCommitCallbacks()
now captures new callbacks added while executingtransaction.on_commit()
callbacks.
Backwards incompatible changes in 4.0¶
Database backend API¶
This section describes changes that may be needed in third-party database backends.
DatabaseOperations.year_lookup_bounds_for_date_field()
andyear_lookup_bounds_for_datetime_field()
methods now take the optionaliso_year
argument in order to support bounds for ISO-8601 week-numbering years.The second argument of
DatabaseSchemaEditor._unique_sql()
and_create_unique_sql()
methods is nowfields
instead ofcolumns
.
django.contrib.gis
¶
Support for PostGIS 2.3 is removed.
Support for GDAL 2.0 and GEOS 3.5 is removed.
Dropped support for PostgreSQL 9.6¶
Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports PostgreSQL 10 and higher.
Also, the minimum supported version of psycopg2
is increased from 2.5.4 to
2.8.4, as psycopg2
2.8.4 is the first release to support Python 3.8.
Dropped support for Oracle 12.2 and 18c¶
Upstream support for Oracle 12.2 ends in March 2022 and for Oracle 18c it ends in June 2021. Django 3.2 will be supported until April 2024. Django 4.0 officially supports Oracle 19c.
CSRF_TRUSTED_ORIGINS
changes¶
Format change¶
Values in the CSRF_TRUSTED_ORIGINS
setting must include the scheme
(e.g. 'http://'
or 'https://'
) instead of only the hostname.
Also, values that started with a dot, must now also include an asterisk before
the dot. For example, change '.example.com'
to 'https://*.example.com'
.
A system check detects any required changes.
Configuring it may now be required¶
As CSRF protection now consults the Origin
header, you may need to set
CSRF_TRUSTED_ORIGINS
, particularly if you allow requests from
subdomains by setting CSRF_COOKIE_DOMAIN
(or
SESSION_COOKIE_DOMAIN
if CSRF_USE_SESSIONS
is enabled) to
a value starting with a dot.
SecurityMiddleware
no longer sets the X-XSS-Protection
header¶
The SecurityMiddleware
no longer sets the
X-XSS-Protection
header if the SECURE_BROWSER_XSS_FILTER
setting is
True
. The setting is removed.
Most modern browsers don’t honor the X-XSS-Protection
HTTP header. You can
use Content-Security-Policy without allowing 'unsafe-inline'
scripts
instead.
If you want to support legacy browsers and set the header, use this line in a custom middleware:
response.headers.setdefault("X-XSS-Protection", "1; mode=block")
Migrations autodetector changes¶
The migrations autodetector now uses model states instead of model classes.
Also, migration operations for ForeignKey
and ManyToManyField
fields no
longer specify attributes which were not passed to the fields during
initialization.
As a side-effect, running makemigrations
might generate no-op
AlterField
operations for ManyToManyField
and ForeignKey
fields in
some cases.
DeleteView
changes¶
DeleteView
now uses
FormMixin
to handle POST requests. As a
consequence, any custom deletion logic in delete()
handlers should be
moved to form_valid()
, or a shared helper method, if required.
Table and column naming scheme changes on Oracle¶
Django 4.0 inadvertently changed the table and column naming scheme on Oracle.
This causes errors for models and fields with names longer than 30 characters.
Unfortunately, renaming some Oracle tables and columns is required. Use the
upgrade script in 33789 to generate RENAME
statements to change naming scheme.
Miscellaneous¶
Support for
cx_Oracle
< 7.0 is removed.To allow serving a Django site on a subpath without changing the value of
STATIC_URL
, the leading slash is removed from that setting (now'static/'
) in the defaultstartproject
template.The
AdminSite
method for the adminindex
view is no longer decorated withnever_cache
when accessed directly, rather than via the recommendedAdminSite.urls
property, orAdminSite.get_urls()
method.Unsupported operations on a sliced queryset now raise
TypeError
instead ofAssertionError
.The undocumented
django.test.runner.reorder_suite()
function is renamed toreorder_tests()
. It now accepts an iterable of tests rather than a test suite, and returns an iterator of tests.Calling
FileSystemStorage.delete()
with an emptyname
now raisesValueError
instead ofAssertionError
.Calling
EmailMultiAlternatives.attach_alternative()
orEmailMessage.attach()
with an invalidcontent
ormimetype
arguments now raiseValueError
instead ofAssertionError
.assertHTMLEqual()
no longer considers a non-boolean attribute without a value equal to an attribute with the same name and value.Tests that fail to load, for example due to syntax errors, now always match when using
test --tag
.The undocumented
django.contrib.admin.utils.lookup_needs_distinct()
function is renamed tolookup_spawns_duplicates()
.The undocumented
HttpRequest.get_raw_uri()
method is removed. TheHttpRequest.build_absolute_uri()
method may be a suitable alternative.The
object
argument of undocumentedModelAdmin.log_addition()
,log_change()
, andlog_deletion()
methods is renamed toobj
.RssFeed
,Atom1Feed
, and their subclasses now emit elements with no content as self-closing tags.NodeList.render()
no longer casts the output ofrender()
method for individual nodes to a string.Node.render()
should always return a string as documented.The
where_class
property ofdjango.db.models.sql.query.Query
and thewhere_class
argument to the privateget_extra_restriction()
method ofForeignObject
andForeignObjectRel
are removed. If needed, initializedjango.db.models.sql.where.WhereNode
instead.The
filter_clause
argument of the undocumentedQuery.add_filter()
method is replaced by two positional argumentsfilter_lhs
andfilter_rhs
.CsrfViewMiddleware
now usesrequest.META['CSRF_COOKIE_NEEDS_UPDATE']
in place ofrequest.META['CSRF_COOKIE_USED']
,request.csrf_cookie_needs_reset
, andresponse.csrf_cookie_set
to track whether the CSRF cookie should be sent. This is an undocumented, private API.The undocumented
TRANSLATOR_COMMENT_MARK
constant is moved fromdjango.template.base
todjango.utils.translation.template
.The
real_apps
argument of the undocumenteddjango.db.migrations.state.ProjectState.__init__()
method must now be a set if provided.RadioSelect
andCheckboxSelectMultiple
widgets are now rendered in<div>
tags so they are announced more concisely by screen readers. If you need the previous behavior, override the widget template with the appropriate template from Django 3.2.The
floatformat
template filter no longer depends on theUSE_L10N
setting and always returns localized output. Use theu
suffix to disable localization.The default value of the
USE_L10N
setting is changed toTrue
. See the Localization section above for more details.As part of the move to zoneinfo,
django.utils.timezone.utc
is changed to aliasdatetime.timezone.utc
.The minimum supported version of
asgiref
is increased from 3.3.2 to 3.4.1.
Features deprecated in 4.0¶
Use of pytz
time zones¶
As part of the move to zoneinfo, use of pytz
time
zones is deprecated.
Accordingly, the is_dst
arguments to the following are also deprecated:
Support for use of pytz
will be removed in Django 5.0.
Time zone support¶
In order to follow good practice, the default value of the USE_TZ
setting will change from False
to True
, and time zone support will be
enabled by default, in Django 5.0.
Note that the default settings.py
file created by
django-admin startproject
includes
USE_TZ = True
since Django 1.4.
You can set USE_TZ
to False
in your project settings before then to
opt-out.
Localization¶
In order to follow good practice, the default value of the USE_L10N
setting
is changed from False
to True
.
Moreover USE_L10N
is deprecated as of this release. Starting with Django
5.0, by default, any date or number displayed by Django will be localized.
The {% localize %}
tag and the localize
/
unlocalize
filters will still be honored by Django.
Miscellaneous¶
SERIALIZE
test setting is deprecated as it can be inferred from thedatabases
with the serialized_rollback option enabled.The undocumented
django.utils.baseconv
module is deprecated.The undocumented
django.utils.datetime_safe
module is deprecated.The default sitemap protocol for sitemaps built outside the context of a request will change from
'http'
to'https'
in Django 5.0.The
extra_tests
argument forDiscoverRunner.build_suite()
andDiscoverRunner.run_tests()
is deprecated.The
ArrayAgg
,JSONBAgg
, andStringAgg
aggregates will returnNone
when there are no rows instead of[]
,[]
, and''
respectively in Django 5.0. If you need the previous behavior, explicitly setdefault
toValue([])
,Value('[]')
, orValue('')
.The
django.contrib.gis.admin.GeoModelAdmin
andOSMGeoAdmin
classes are deprecated. UseModelAdmin
andGISModelAdmin
instead.Since form rendering now uses the template engine, the undocumented
BaseForm._html_output()
helper method is deprecated.The ability to return a
str
fromErrorList
andErrorDict
is deprecated. It is expected these methods return aSafeString
.
Features removed in 4.0¶
These features have reached the end of their deprecation cycle and are removed in Django 4.0.
See Features deprecated in 3.0 for details on these changes, including how to remove usage of these features.
django.utils.http.urlquote()
,urlquote_plus()
,urlunquote()
, andurlunquote_plus()
are removed.django.utils.encoding.force_text()
andsmart_text()
are removed.django.utils.translation.ugettext()
,ugettext_lazy()
,ugettext_noop()
,ungettext()
, andungettext_lazy()
are removed.django.views.i18n.set_language()
doesn’t set the user language inrequest.session
(key_language
).alias=None
is required in the signature ofdjango.db.models.Expression.get_group_by_cols()
subclasses.django.utils.text.unescape_entities()
is removed.django.utils.http.is_safe_url()
is removed.
See Features deprecated in 3.1 for details on these changes, including how to remove usage of these features.
The
PASSWORD_RESET_TIMEOUT_DAYS
setting is removed.The
isnull
lookup no longer allows using non-boolean values as the right-hand side.The
django.db.models.query_utils.InvalidQuery
exception class is removed.The
django-admin.py
entry point is removed.The
HttpRequest.is_ajax()
method is removed.Support for the pre-Django 3.1 encoding format of cookies values used by
django.contrib.messages.storage.cookie.CookieStorage
is removed.Support for the pre-Django 3.1 password reset tokens in the admin site (that use the SHA-1 hashing algorithm) is removed.
Support for the pre-Django 3.1 encoding format of sessions is removed.
Support for the pre-Django 3.1
django.core.signing.Signer
signatures (encoded with the SHA-1 algorithm) is removed.Support for the pre-Django 3.1
django.core.signing.dumps()
signatures (encoded with the SHA-1 algorithm) indjango.core.signing.loads()
is removed.Support for the pre-Django 3.1 user sessions (that use the SHA-1 algorithm) is removed.
The
get_response
argument fordjango.utils.deprecation.MiddlewareMixin.__init__()
is required and doesn’t acceptNone
.The
providing_args
argument fordjango.dispatch.Signal
is removed.The
length
argument fordjango.utils.crypto.get_random_string()
is required.The
list
message forModelMultipleChoiceField
is removed.Support for passing raw column aliases to
QuerySet.order_by()
is removed.The
NullBooleanField
model field is removed, except for support in historical migrations.django.conf.urls.url()
is removed.The
django.contrib.postgres.fields.JSONField
model field is removed, except for support in historical migrations.django.contrib.postgres.fields.jsonb.KeyTransform
anddjango.contrib.postgres.fields.jsonb.KeyTextTransform
are removed.django.contrib.postgres.forms.JSONField
is removed.The
{% ifequal %}
and{% ifnotequal %}
template tags are removed.The
DEFAULT_HASHING_ALGORITHM
transitional setting is removed.