April 6, 2021
Welcome to Django 3.2!
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.1 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 3.2 is designated as a long-term support release. It will receive security updates for at least three years after its release. Support for the previous LTS, Django 2.2, will end in April 2022.
Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We highly recommend and only officially support the latest release of each series.
Most pluggable applications define an
apps.py submodule. Many define a
pointing to this class in their
apps.py submodule exists and defines a single
AppConfig subclass, Django now uses that configuration
automatically, so you can remove
default_app_config made it possible to declare only the application’s path
'django.contrib.admin') rather than the
app config’s path (e.g.
'django.contrib.admin.apps.AdminConfig'). It was
introduced for backwards-compatibility with the former style, with the intent
to switch the ecosystem to the latter, but the switch didn’t happen.
default_app_config is no longer
needed. As a consequence, it’s deprecated.
See Configuring applications for full details.
When defining a model, if no field in a model is defined with
primary_key=True an implicit
primary key is added. The type of this implicit primary key can now be
controlled via the
DEFAULT_AUTO_FIELD setting and
attribute. No more needing to override primary keys in all models.
Maintaining the historical behavior, the default value for
with 3.2 new projects are generated with
DEFAULT_AUTO_FIELD set to
BigAutoField. Also, new apps are generated with
BigAutoField. In a future Django release the
default value of
DEFAULT_AUTO_FIELD will be changed to
DEFAULT_AUTO_FIELD = "django.db.models.AutoField"
or configure it on a per-app basis:
from django.apps import AppConfig class MyAppConfig(AppConfig): default_auto_field = "django.db.models.AutoField" name = "my_app"
or on a per-model basis:
from django.db import models class MyModel(models.Model): id = models.AutoField(primary_key=True)
In anticipation of the changing default, a system check will provide a warning
if you do not have an explicit setting for
When changing the value of
DEFAULT_AUTO_FIELD, migrations for the
primary key of existing auto-created through tables cannot be generated
currently. See the
DEFAULT_AUTO_FIELD docs for details on migrating
from django.db import models from django.db.models import F, Index, Value from django.db.models.functions import Lower, Upper class MyModel(models.Model): first_name = models.CharField(max_length=255) last_name = models.CharField(max_length=255) height = models.IntegerField() weight = models.IntegerField() class Meta: indexes = [ Index( Lower("first_name"), Upper("last_name").desc(), name="first_last_name_idx", ), Index( F("height") / (F("weight") + Value(5)), name="calc_idx", ), ]
Functional indexes are added to models using the
django.core.cache.backends.memcached.PyMemcacheCache cache backend
allows using the pymemcache library for memcached.
or higher is required. For more details, see the documentation on caching
@display decorator has the advantage that it is now
possible to use the
@property decorator when needing to specify attributes
on the custom method. Prior to this it was necessary to use the
function instead after assigning the required attributes to the method.
Using decorators has the advantage that these options are more discoverable as they can be suggested by completion utilities in code editors. They are merely a convenience and still set the same attributes on the functions under the hood.
ModelAdmin.search_fields now allows searching against quoted phrases
Read-only related fields are now rendered as navigable links if target models are registered in the admin.
The admin now supports theming, and includes a dark theme that is enabled according to browser settings. See Theming support for more details.
The admin now installs a final catch-all view that redirects unauthenticated users to the login page, regardless of whether the URL is otherwise valid. This protects against a potential model enumeration privacy issue.
Although not recommended, you may set the new
False to disable the
The default iteration count for the PBKDF2 password hasher is increased from 216,000 to 260,000.
The default variant for the Argon2 password hasher is changed to Argon2id.
parallelism are increased to 102,400 and 8
respectively to match the
memory_cost pushes the required memory from 512 KB to 100
MB. This is still rather conservative but can lead to problems in memory
constrained environments. If this is the case, the existing hasher can be
subclassed to override the defaults.
The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers is increased from 71 to 128 bits.
absolute_max argument for
allows customizing the maximum number of forms that can be instantiated when
POST data. See Limiting the maximum number of instantiated forms for more details.
ExclusionConstraint.include attribute allows creating
covering exclusion constraints on PostgreSQL 12+.
ExclusionConstraint.opclasses attribute allows setting PostgreSQL
JSONBAgg.ordering attribute determines the ordering of the
JSONBAgg.distinct attribute determines if aggregated values
will be distinct.
now checks that the extension already exists in the database and skips the
migration if so.
ArrayField now allow
(non-nested) arrays containing expressions as right-hand sides.
Third-party database backends can now skip or mark as expected failures
tests in Django’s test suite using the new
callback allows handling interrupted uploads.
absolute_max argument for
customizing the maximum number of forms that can be instantiated when
POST data. See Limiting the maximum number of instantiated forms for more details.
can_delete_extra argument for
removal of the option to delete extra forms. See
can_delete_extra for more information.
BaseFormSet now reports a user facing error,
rather than raising an exception, when the management form is missing or has
been tampered with. To customize this error message, pass the
error_messages argument with the key
instantiating the formset.
loaddata now supports fixtures stored in XZ archives (
LZMA archives (
dumpdata now can compress data in the
makemigrations can now be called without an active database
connection. In that case, check for a consistent migration history is
BaseCommand.requires_system_checks now supports specifying a list of
tags. System checks registered in the chosen tags will be checked for errors
prior to executing the command. In previous versions, either all or none
of the system checks were performed.
Support for colored terminal output on Windows is updated. Various modern terminal environments are automatically detected, and the options for enabling support in other cases are improved. See Syntax coloring for more details.
no_key parameter for
supported on PostgreSQL, allows acquiring weaker locks that don’t block the
creation of rows that reference locked rows through a foreign key.
When() expression now allows
condition argument with
UniqueConstraint.opclasses attribute allows setting
PostgreSQL operator classes.
QuerySet.update() method now respects the
order_by() clause on
MySQL and MariaDB.
FilteredRelation() now supports
of argument of
QuerySet.select_for_update() is now allowed
on MySQL 8.0.1+.
Value() expression now
automatically resolves its
output_field to the appropriate
Field subclass based on the type of
uuid.UUID instances. As a
consequence, resolving an
output_field for database functions and
combined expressions may now crash with mixed types when using
You will need to explicitly set the
output_field in such cases.
QuerySet.alias() method allows creating reusable aliases for
expressions that don’t need to be selected but are used for filtering,
ordering, or as a part of complex expressions.
Collate function allows
filtering and ordering by specified database collations.
Random database function.
durable argument for
guarantees that changes made in the atomic block will be committed if the
block exits without errors. A nested atomic block marked as durable will
JSONObject database function.
allows generating a page range with some of the values elided. If there are a
large number of pages, this can be helpful for generating a reasonable number
of page links in a template.
Response headers are now stored in
HttpResponse.headers. This can be
used instead of the original dict-like interface of
Both interfaces will continue to be supported. See
Setting header fields for details.
SECRET_KEY setting is now checked for a valid value upon first
access, rather than when settings are first loaded. This enables running
management commands that do not rely on the
SECRET_KEY without needing to
provide a value. As a consequence of this, calling
configure() without providing a valid
SECRET_KEY, and then going on to access
settings.SECRET_KEY will now
Signer.unsign_object() methods allow
signing complex data structures. See Protecting complex data structures for more
Signal.send_robust() now logs
Objects assigned to class attributes in
now isolated for each test method. Such objects are now required to support
creating deep copies with
copy.deepcopy(). Assigning objects which
deepcopy() is deprecated and will be removed in Django 4.1.
Client now preserves the request query string when
following 307 and 308 redirects.
TestCase.captureOnCommitCallbacks() method captures callback
functions passed to
transaction.on_commit() in a list. This allows you to test such
callbacks without using the slower
TransactionTestCase.assertQuerysetEqual() now supports direct
comparison against another queryset rather than being restricted to
comparison against a list of string representations of objects when using the
default value for the
depth parameter of
django.utils.timesince.timeuntil() functions allows specifying the number
of adjacent time units to return.
This section describes changes that may be needed in third-party database backends.
DatabaseFeatures.introspected_field_types property replaces these
Third-party database backends must implement support for column database
TextFields or set
non-deterministic collations are not supported, set
DatabaseOperations.random_function_sql() is removed in favor of the new
Random database function.
DatabaseOperations.time_trunc_sql() now take the optional
argument in order to truncate in a specific timezone.
DatabaseClient.runshell() now gets arguments and an optional dictionary
with environment variables to the underlying command-line client from
DatabaseClient.settings_to_cmd_args_env() method. Third-party database
backends must implement
Third-party database backends must implement support for functional indexes
Index.expressions) or set
is not a part of the
CREATE INDEX statement, set
Pagination links in the admin are now 1-indexed instead of 0-indexed, i.e.
the query string for the first page is
?p=1 instead of
The new admin catch-all view will break URL patterns routed after the admin
URLs and matching the admin URL prefix. You can either adjust your URL
ordering or, if necessary, set
disabling the catch-all view. See What’s new in Django 3.2 for more details.
ModelAdmin.prepopulated_fields no longer strips English stop words,
Support for PostGIS 2.2 is removed.
The Oracle backend now clones polygons (and geometry collections containing polygons) before reorienting them and saving them to the database. They are no longer mutated in place. You might notice this if you use the polygons after a model is saved.
Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports PostgreSQL 9.6 and higher.
The end of upstream support for MySQL 5.6 is April 2021. Django 3.2 supports MySQL 5.7 and higher.
Django now supports non-
pytz time zones, such as Python 3.9+’s
zoneinfo module and its backport.
SpatiaLiteOperations.proj4_version() method is renamed
slugify() now removes leading and trailing dashes
argon2-cffi < 19.1.0 is removed.
The cache keys no longer includes the language when internationalization is
USE_I18N = False) and localization is enabled
USE_L10N = True). After upgrading to Django 3.2 in such configurations,
the first request to any previously cached value will be a cache miss.
When an application defines an
AppConfig subclass in
apps.py submodule, Django now uses this configuration automatically,
even if it isn’t enabled with
default = False
AppConfig subclass if you need to prevent this
behavior. See What’s new in Django 3.2 for more details.
Instantiating an abstract model now raises
Keyword arguments to
setup_databases() are now
django.utils.http.limited_parse_qsl() function is
removed. Please use
django.db.models.Field equality operator now correctly
distinguishes inherited field instances across models. Additionally, the
ordering of such fields is now defined.
django.core.files.locks.lock() function now returns
False if the file cannot be locked, instead of raising
The password reset mechanism now invalidates tokens when the user email is changed.
django.contrib.auth.forms.ReadOnlyPasswordHashField form field is now
disabled by default. Therefore
UserChangeForm.clean_password() is no longer required to return the
decr_version() cache operations now
None stored in the cache, in the same way as any other
value, instead of behaving as though the key didn’t exist.
Due to a
python-memcached limitation, the previous behavior is kept for
The minimum supported version of SQLite is increased from 3.8.3 to 3.9.0.
The minimum supported version of
asgiref is increased from 3.2.10 to
Using a boolean value in
'__all__' instead of
 (an empty list)
whitelist argument and
domain_whitelist attribute of
EmailValidator are deprecated. Use
allowlist instead of
domain_allowlist instead of
domain_whitelist. You may need to rename
whitelist in existing
default_app_config application configuration variable is deprecated,
due to the now automatic
AppConfig discovery. See What’s new in Django 3.2
for more details.
repr() on a queryset in
TransactionTestCase.assertQuerysetEqual(), when compared to string
values, is deprecated. If you need the previous behavior, explicitly set
django.core.cache.backends.memcached.MemcachedCache backend is
python-memcached has some problems and seems to be
The format of messages used by
django.contrib.messages.storage.cookie.CookieStorage is different from
the format generated by older versions of Django. Support for the old format
remains until Django 4.1.