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.
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.
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.
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.
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.
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.
django.contrib.admin¶admin/base.html template now has a new block header which
contains the admin site header.ModelAdmin.get_formset_kwargs() method allows customizing the
keyword arguments passed to the constructor of a formset.model which contains the model class for each
model is added to the AdminSite.each_context() method.ModelAdmin.search_help_text attribute allows specifying a
descriptive text for the search box.InlineModelAdmin.verbose_name_plural attribute now fallbacks to
the InlineModelAdmin.verbose_name + 's'.django.contrib.admindocs¶ROOT_URLCONF is not
a string.admindocs now shows cached properties.django.contrib.auth¶LoginView.next_page
attribute and
get_default_redirect_url() method
allow customizing the redirect after login.django.contrib.gis¶GDALRaster now allows creating rasters in
any GDAL virtual filesystem.GISModelAdmin class allows
customizing the widget used for GeometryField. This is encouraged instead
of deprecated GeoModelAdmin and OSMGeoAdmin.django.contrib.postgres¶AddConstraintNotValid
operation allows creating check constraints on PostgreSQL without verifying
that all existing rows satisfy the new constraint.ValidateConstraint
operation allows validating check constraints which were created using
AddConstraintNotValid on
PostgreSQL.ArraySubquery()
expression allows using subqueries to construct lists of values on
PostgreSQL.trigram_word_similar lookup, and the
TrigramWordDistance() and
TrigramWordSimilarity() expressions allow
using trigram word similarity.django.contrib.staticfiles¶ManifestStaticFilesStorage now
replaces paths to JavaScript source map references with their hashed
counterparts.manifest_storage argument of
ManifestFilesMixin and
ManifestStaticFilesStorage
allows customizing the manifest file storage.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 have a prefixed names, e.g. aadd(), aget(), aset(),
aget_or_set(), or adelete_many().
Going forward, the a prefix will be used for async variants of methods
generally.
Origin header, if present. To facilitate
this, some changes to the
CSRF_TRUSTED_ORIGINS setting are required.ModelChoiceField now includes the provided value in
the params argument of a raised
ValidationError for the invalid_choice
error message. This allows custom error messages to use the %(value)s
placeholder.BaseFormSet now renders non-form errors with
an additional class of nonform to help distinguish them from
form-specific errors.BaseFormSet now allows customizing the widget
used when deleting forms via
can_delete by setting the
deletion_widget attribute or
overriding get_deletion_widget()
method.DeleteView now uses
FormMixin, allowing you to provide a
Form subclass, with a checkbox for example, to confirm
deletion. In addition, this allows DeleteView to function with
django.contrib.messages.views.SuccessMessageMixin.
In accordance with FormMixin, object deletion for POST requests is
handled in form_valid(). Custom delete logic in delete() handlers
should be moved to form_valid(), or a shared helper method, as needed.
runserver management command now supports the
--skip-checks option.dbshell now supports specifying a password file.shell command now respects sys.__interactivehook__
at startup. This allows loading shell history between interactive sessions.
As a consequence, readline is no longer loaded if running in isolated
mode.BaseCommand.suppressed_base_arguments attribute
allows suppressing unsupported default command options in the help output.startapp --exclude and startproject --exclude
options allow excluding directories from the template.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.precision argument of the
Round() 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.Expression.empty_result_set_value attribute allows
specifying a value to return when the function is used over an empty result
set.skip_locked argument of QuerySet.select_for_update() is now
allowed on MariaDB 10.6+.Lookup expressions may now be used in QuerySet
annotations, aggregations, and directly in filters.None.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 the SECURE_CROSS_ORIGIN_OPENER_POLICY setting to None.stdout argument for pre_migrate()
and post_migrate() signals allows redirecting
output to a stream-like object. It should be preferred over
sys.stdout and print() when emitting verbose output in
order to allow proper capture when testing.floatformat template filter now allows using the u suffix to
force disabling localization.serialized_aliases argument of
django.test.utils.setup_databases() determines which
DATABASES aliases test databases should have their state
serialized to allow usage of the
serialized_rollback feature.--buffer option
with parallel tests.logger argument to DiscoverRunner
allows a Python logger to be used for logging.DiscoverRunner.log() method provides a way to log messages
that uses the DiscoverRunner.logger, or prints to the console if not set.--shuffle option
to execute tests in a random order.test --parallel option now supports the value auto to run
one test process for each processor core.TestCase.captureOnCommitCallbacks() now captures new callbacks added
while executing transaction.on_commit() callbacks.This section describes changes that may be needed in third-party database backends.
DatabaseOperations.year_lookup_bounds_for_date_field() and
year_lookup_bounds_for_datetime_field() methods now take the optional
iso_year argument in order to support bounds for ISO-8601 week-numbering
years.DatabaseSchemaEditor._unique_sql() and
_create_unique_sql() methods is now fields instead of columns.django.contrib.gis¶Upstream support for PostgreSQL 9.6 ends in November 2021. Django 4.0 supports PostgreSQL 10 and higher.
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¶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.
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')
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.
cx_Oracle < 7.0 is removed.STATIC_URL, the leading slash is removed from that setting (now
'static/') in the default startproject template.AdminSite method for the admin index
view is no longer decorated with never_cache when accessed directly,
rather than via the recommended AdminSite.urls property, or
AdminSite.get_urls() method.TypeError instead
of AssertionError.django.test.runner.reorder_suite() function is renamed
to reorder_tests(). It now accepts an iterable of tests rather than a
test suite, and returns an iterator of tests.FileSystemStorage.delete() with an empty name now raises
ValueError instead of AssertionError.EmailMultiAlternatives.attach_alternative() or
EmailMessage.attach() with an invalid content or mimetype
arguments now raise ValueError instead of AssertionError.assertHTMLEqual() no longer considers a
non-boolean attribute without a value equal to an attribute with the same
name and value.test --tag.django.contrib.admin.utils.lookup_needs_distinct()
function is renamed to lookup_spawns_duplicates().HttpRequest.get_raw_uri() method is removed. The
HttpRequest.build_absolute_uri() method may be a suitable alternative.object argument of undocumented ModelAdmin.log_addition(),
log_change(), and log_deletion() methods is renamed to obj.RssFeed,
Atom1Feed, and their subclasses now emit
elements with no content as self-closing tags.NodeList.render() no longer casts the output of render() method for
individual nodes to a string. Node.render() should always return a string
as documented.where_class property of django.db.models.sql.query.Query and the
where_class argument to the private get_extra_restriction() method of
ForeignObject and ForeignObjectRel are removed. If needed, initialize
django.db.models.sql.where.WhereNode instead.filter_clause argument of the undocumented Query.add_filter()
method is replaced by two positional arguments filter_lhs and
filter_rhs.CsrfViewMiddleware now uses
request.META['CSRF_COOKIE_NEEDS_UPDATE'] in place of
request.META['CSRF_COOKIE_USED'], request.csrf_cookie_needs_reset,
and response.csrf_cookie_set to track whether the CSRF cookie should be
sent. This is an undocumented, private API.TRANSLATOR_COMMENT_MARK constant is moved from
django.template.base to django.utils.translation.template.real_apps argument of the undocumented
django.db.migrations.state.ProjectState.__init__() method must now be a
set if provided.RadioSelect and
CheckboxSelectMultiple 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.floatformat template filter no longer depends on the
USE_L10N setting and always returns localized output. Use the u
suffix to disable localization.USE_L10N setting is changed to True. See the
Localization section above for more details.django.utils.timezone.utc is changed to alias
datetime.timezone.utc.asgiref is increased from 3.3.2 to
3.4.1.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:
django.db.models.query.QuerySet.datetimes()django.db.models.functions.Trunc()django.db.models.functions.TruncSecond()django.db.models.functions.TruncMinute()django.db.models.functions.TruncHour()django.db.models.functions.TruncDay()django.db.models.functions.TruncWeek()django.db.models.functions.TruncMonth()django.db.models.functions.TruncQuarter()django.db.models.functions.TruncYear()django.utils.timezone.make_aware()Support for use of pytz will be removed in Django 5.0.
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.
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.
SERIALIZE test setting is deprecated as it can be inferred from the
databases with the
serialized_rollback option enabled.django.utils.baseconv module is deprecated.django.utils.datetime_safe module is deprecated.'http' to 'https' in Django 5.0.extra_tests argument for DiscoverRunner.build_suite() and
DiscoverRunner.run_tests() is deprecated.ArrayAgg,
JSONBAgg, and
StringAgg aggregates will return
None when there are no rows instead of [], [], and ''
respectively in Django 5.0. If you need the previous behavior, explicitly set
default to Value([]), Value('[]'), or Value('').django.contrib.gis.admin.GeoModelAdmin and OSMGeoAdmin classes
are deprecated. Use ModelAdmin and
GISModelAdmin instead.BaseForm._html_output() helper method is deprecated.str from ErrorList and ErrorDict is
deprecated. It is expected these methods return a SafeString.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(), and
urlunquote_plus() are removed.django.utils.encoding.force_text() and smart_text() are removed.django.utils.translation.ugettext(), ugettext_lazy(),
ugettext_noop(), ungettext(), and ungettext_lazy() are removed.django.views.i18n.set_language() doesn’t set the user language in
request.session (key _language).alias=None is required in the signature of
django.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.
PASSWORD_RESET_TIMEOUT_DAYS setting is removed.isnull lookup no longer allows using non-boolean values as the
right-hand side.django.db.models.query_utils.InvalidQuery exception class is removed.django-admin.py entry point is removed.HttpRequest.is_ajax() method is removed.django.contrib.messages.storage.cookie.CookieStorage is removed.django.core.signing.Signer signatures
(encoded with the SHA-1 algorithm) is removed.django.core.signing.dumps() signatures
(encoded with the SHA-1 algorithm) in django.core.signing.loads() is
removed.get_response argument for
django.utils.deprecation.MiddlewareMixin.__init__() is required and
doesn’t accept None.providing_args argument for django.dispatch.Signal is removed.length argument for django.utils.crypto.get_random_string() is
required.list message for ModelMultipleChoiceField is removed.QuerySet.order_by() is removed.NullBooleanField model field is removed, except for support in
historical migrations.django.conf.urls.url() is removed.django.contrib.postgres.fields.JSONField model field is removed,
except for support in historical migrations.django.contrib.postgres.fields.jsonb.KeyTransform and
django.contrib.postgres.fields.jsonb.KeyTextTransform are removed.django.contrib.postgres.forms.JSONField is removed.{% ifequal %} and {% ifnotequal %} template tags are removed.DEFAULT_HASHING_ALGORITHM transitional setting is removed.Dec 13, 2021