Django 3.2 release notes¶
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.
Python compatibility¶
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.
What’s new in Django 3.2¶
Automatic AppConfig
discovery¶
Most pluggable applications define an AppConfig
subclass
in an apps.py
submodule. Many define a default_app_config
variable
pointing to this class in their __init__.py
.
When the apps.py
submodule exists and defines a single
AppConfig
subclass, Django now uses that configuration
automatically, so you can remove default_app_config
.
default_app_config
made it possible to declare only the application’s path
in INSTALLED_APPS
(e.g. '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.
With automatic AppConfig
discovery, default_app_config
is no longer
needed. As a consequence, it’s deprecated.
See Configuring applications for full details.
Customizing type of auto-created primary keys¶
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
AppConfig.default_auto_field
attribute. No more needing to override primary keys in all models.
Maintaining the historical behavior, the default value for
DEFAULT_AUTO_FIELD
is AutoField
. Starting
with 3.2 new projects are generated with DEFAULT_AUTO_FIELD
set to
BigAutoField
. Also, new apps are generated with
AppConfig.default_auto_field
set to BigAutoField
. In a future Django release the
default value of DEFAULT_AUTO_FIELD
will be changed to
BigAutoField
.
To avoid unwanted migrations in the future, either explicitly set
DEFAULT_AUTO_FIELD
to AutoField
:
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 DEFAULT_AUTO_FIELD
.
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
such tables.
Functional indexes¶
The new *expressions
positional
argument of Index()
enables creating
functional indexes on expressions and database functions. For example:
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
Meta.indexes
option.
pymemcache
support¶
The new django.core.cache.backends.memcached.PyMemcacheCache
cache backend
allows using the pymemcache library for memcached. pymemcache
3.4.0 or
higher is required. For more details, see the documentation on caching in
Django.
New decorators for the admin site¶
The new display()
decorator allows for easily
adding options to custom display functions that can be used with
list_display
or
readonly_fields
.
Likewise, the new action()
decorator allows for
easily adding options to action functions that can be used with
actions
.
Using the @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 property()
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.
Minor features¶
django.contrib.admin
¶
ModelAdmin.search_fields
now allows searching against quoted phrases with spaces.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.
ModelAdmin.autocomplete_fields
now respectsForeignKey.to_field
andForeignKey.limit_choices_to
when searching a related model.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
AdminSite.final_catch_all_view
toFalse
to disable the catch-all view.
django.contrib.auth
¶
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.
memory_cost
andparallelism
are increased to 102,400 and 8 respectively to match theargon2-cffi
defaults.Increasing 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.
django.contrib.contenttypes
¶
- The new
absolute_max
argument forgeneric_inlineformset_factory()
allows customizing the maximum number of forms that can be instantiated when supplyingPOST
data. See Limiting the maximum number of instantiated forms for more details. - The new
can_delete_extra
argument forgeneric_inlineformset_factory()
allows removal of the option to delete extra forms. Seecan_delete_extra
for more information.
django.contrib.gis
¶
- The
GDALRaster.transform()
method now supportsSpatialReference
. - The
DataSource
class now supportspathlib.Path
. - The
LayerMapping
class now supportspathlib.Path
.
django.contrib.postgres
¶
- The new
ExclusionConstraint.include
attribute allows creating covering exclusion constraints on PostgreSQL 12+. - The new
ExclusionConstraint.opclasses
attribute allows setting PostgreSQL operator classes. - The new
JSONBAgg.ordering
attribute determines the ordering of the aggregated elements. - The new
JSONBAgg.distinct
attribute determines if aggregated values will be distinct. - The
CreateExtension
operation now checks that the extension already exists in the database and skips the migration if so. - The new
CreateCollation
andRemoveCollation
operations allow creating and dropping collations on PostgreSQL. See Managing collations using migrations for more details. - Lookups for
ArrayField
now allow (non-nested) arrays containing expressions as right-hand sides. - The new
OpClass()
expression allows creating functional indexes on expressions with a custom operator class. See Functional indexes for more details.
django.contrib.sitemaps
¶
- The new
Sitemap
attributesalternates
,languages
andx_default
allow generating sitemap alternates to localized versions of your pages.
django.contrib.syndication
¶
- The new
item_comments
hook allows specifying a comments URL per feed item.
Database backends¶
- Third-party database backends can now skip or mark as expected failures
tests in Django’s test suite using the new
DatabaseFeatures.django_test_skips
anddjango_test_expected_failures
attributes.
Decorators¶
- The new
no_append_slash()
decorator allows individual views to be excluded fromAPPEND_SLASH
URL normalization.
Error Reporting¶
- Custom
ExceptionReporter
subclasses can now define thehtml_template_path
andtext_template_path
properties to override the templates used to render exception reports.
File Uploads¶
- The new
FileUploadHandler.upload_interrupted()
callback allows handling interrupted uploads.
Forms¶
- The new
absolute_max
argument forformset_factory()
,inlineformset_factory()
, andmodelformset_factory()
allows customizing the maximum number of forms that can be instantiated when supplyingPOST
data. See Limiting the maximum number of instantiated forms for more details. - The new
can_delete_extra
argument forformset_factory()
,inlineformset_factory()
, andmodelformset_factory()
allows removal of the option to delete extra forms. Seecan_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 theerror_messages
argument with the key'missing_management_form'
when instantiating the formset.
Generic Views¶
- The
week_format
attributes ofWeekMixin
andWeekArchiveView
now support the'%V'
ISO 8601 week format.
Management Commands¶
loaddata
now supports fixtures stored in XZ archives (.xz
) and LZMA archives (.lzma
).dumpdata
now can compress data in thebz2
,gz
,lzma
, orxz
formats.makemigrations
can now be called without an active database connection. In that case, check for a consistent migration history is skipped.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.
Migrations¶
- The new
Operation.migration_name_fragment
property allows providing a filename fragment that will be used to name a migration containing only that operation. - Migrations now support serialization of pure and concrete path objects from
pathlib
, andos.PathLike
instances.
Models¶
- The new
no_key
parameter forQuerySet.select_for_update()
, 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 using thecondition
argument withlookups
.- The new
Index.include
andUniqueConstraint.include
attributes allow creating covering indexes and covering unique constraints on PostgreSQL 11+. - The new
UniqueConstraint.opclasses
attribute allows setting PostgreSQL operator classes. - The
QuerySet.update()
method now respects theorder_by()
clause on MySQL and MariaDB. FilteredRelation()
now supports nested relations.- The
of
argument ofQuerySet.select_for_update()
is now allowed on MySQL 8.0.1+. Value()
expression now automatically resolves itsoutput_field
to the appropriateField
subclass based on the type of its providedvalue
forbool
,bytes
,float
,int
,str
,datetime.date
,datetime.datetime
,datetime.time
,datetime.timedelta
,decimal.Decimal
, anduuid.UUID
instances. As a consequence, resolving anoutput_field
for database functions and combined expressions may now crash with mixed types when usingValue()
. You will need to explicitly set theoutput_field
in such cases.- The new
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. - The new
Collate
function allows filtering and ordering by specified database collations. - The
field_name
argument ofQuerySet.in_bulk()
now accepts distinct fields if there’s only one field specified inQuerySet.distinct()
. - The new
tzinfo
parameter of theTruncDate
andTruncTime
database functions allows truncating datetimes in a specific timezone. - The new
db_collation
argument forCharField
andTextField
allows setting a database collation for the field. - Added the
Random
database function. - Aggregation functions,
F()
,OuterRef()
, and other expressions now allow using transforms. See Expressions can reference transforms for details. - The new
durable
argument foratomic()
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 raise aRuntimeError
. - Added the
JSONObject
database function.
Pagination¶
- The new
django.core.paginator.Paginator.get_elided_page_range()
method 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.
Requests and Responses¶
- Response headers are now stored in
HttpResponse.headers
. This can be used instead of the original dict-like interface ofHttpResponse
objects. Both interfaces will continue to be supported. See Setting header fields for details. - The new
headers
parameter ofHttpResponse
,SimpleTemplateResponse
, andTemplateResponse
allows setting responseheaders
on instantiation.
Security¶
The
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 theSECRET_KEY
without needing to provide a value. As a consequence of this, callingconfigure()
without providing a validSECRET_KEY
, and then going on to accesssettings.SECRET_KEY
will now raise anImproperlyConfigured
exception.The new
Signer.sign_object()
andSigner.unsign_object()
methods allow signing complex data structures. See Protecting complex data structures for more details.Also,
signing.dumps()
andloads()
become shortcuts forTimestampSigner.sign_object()
andunsign_object()
.
Serialization¶
Signals¶
Signal.send_robust()
now logs exceptions.
Templates¶
floatformat
template filter now allows using theg
suffix to force grouping by theTHOUSAND_SEPARATOR
for the active locale.- Templates cached with Cached template loaders are now correctly reloaded in development.
Tests¶
- Objects assigned to class attributes in
TestCase.setUpTestData()
are now isolated for each test method. Such objects are now required to support creating deep copies withcopy.deepcopy()
. Assigning objects which don’t supportdeepcopy()
is deprecated and will be removed in Django 4.1. DiscoverRunner
now enablesfaulthandler
by default. This can be disabled by using thetest --no-faulthandler
option.DiscoverRunner
and thetest
management command can now track timings, including database setup and total run time. This can be enabled by using thetest --timing
option.Client
now preserves the request query string when following 307 and 308 redirects.- The new
TestCase.captureOnCommitCallbacks()
method captures callback functions passed totransaction.on_commit()
in a list. This allows you to test such callbacks without using the slowerTransactionTestCase
. 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 thetransform
argument.
Utilities¶
- The new
depth
parameter ofdjango.utils.timesince.timesince()
anddjango.utils.timesince.timeuntil()
functions allows specifying the number of adjacent time units to return.
Validators¶
- Built-in validators now include the provided value in the
params
argument of a raisedValidationError
. This allows custom error messages to use the%(value)s
placeholder. - The
ValidationError
equality operator now ignoresmessages
andparams
ordering.
Backwards incompatible changes in 3.2¶
Database backend API¶
This section describes changes that may be needed in third-party database backends.
- The new
DatabaseFeatures.introspected_field_types
property replaces these features:can_introspect_autofield
can_introspect_big_integer_field
can_introspect_binary_field
can_introspect_decimal_field
can_introspect_duration_field
can_introspect_ip_address_field
can_introspect_positive_integer_field
can_introspect_small_integer_field
can_introspect_time_field
introspected_big_auto_field_type
introspected_small_auto_field_type
introspected_boolean_field_type
- To enable support for covering indexes (
Index.include
) and covering unique constraints (UniqueConstraint.include
), setDatabaseFeatures.supports_covering_indexes
toTrue
. - Third-party database backends must implement support for column database
collations on
CharField
s andTextField
s or setDatabaseFeatures.supports_collation_on_charfield
andDatabaseFeatures.supports_collation_on_textfield
toFalse
. If non-deterministic collations are not supported, setsupports_non_deterministic_collations
toFalse
. DatabaseOperations.random_function_sql()
is removed in favor of the newRandom
database function.DatabaseOperations.date_trunc_sql()
andDatabaseOperations.time_trunc_sql()
now take the optionaltzname
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 fromDatabaseClient.settings_to_cmd_args_env()
method. Third-party database backends must implementDatabaseClient.settings_to_cmd_args_env()
or overrideDatabaseClient.runshell()
.- Third-party database backends must implement support for functional indexes
(
Index.expressions
) or setDatabaseFeatures.supports_expression_indexes
toFalse
. IfCOLLATE
is not a part of theCREATE INDEX
statement, setDatabaseFeatures.collate_as_index_expression
toTrue
.
django.contrib.admin
¶
- 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?p=0
. - 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
AdminSite.final_catch_all_view
toFalse
, disabling the catch-all view. See What’s new in Django 3.2 for more details. - Minified JavaScript files are no longer included with the admin. If you require these files to be minified, consider using a third party app or external build tool. The minified vendored JavaScript files packaged with the admin (e.g. jquery.min.js) are still included.
ModelAdmin.prepopulated_fields
no longer strips English stop words, such as'a'
or'an'
.
django.contrib.gis
¶
- 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.
Dropped support for PostgreSQL 9.5¶
Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports PostgreSQL 9.6 and higher.
Dropped support for MySQL 5.6¶
The end of upstream support for MySQL 5.6 is April 2021. Django 3.2 supports MySQL 5.7 and higher.
Miscellaneous¶
Django now supports non-
pytz
time zones, such as Python 3.9+’szoneinfo
module and its backport.The undocumented
SpatiaLiteOperations.proj4_version()
method is renamed toproj_version()
.slugify()
now removes leading and trailing dashes and underscores.The
intcomma
andintword
template filters no longer depend on theUSE_L10N
setting.Support for
argon2-cffi
< 19.1.0 is removed.The cache keys no longer includes the language when internationalization is disabled (
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.ForeignKey.validate()
now uses_base_manager
rather than_default_manager
to check that related instances exist.When an application defines an
AppConfig
subclass in anapps.py
submodule, Django now uses this configuration automatically, even if it isn’t enabled withdefault_app_config
. Setdefault = False
in theAppConfig
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
TypeError
.Keyword arguments to
setup_databases()
are now keyword-only.The undocumented
django.utils.http.limited_parse_qsl()
function is removed. Please useurllib.parse.parse_qsl()
instead.django.test.utils.TestContextDecorator
now usesaddCleanup()
so that cleanups registered in thesetUp()
method are called beforeTestContextDecorator.disable()
.SessionMiddleware
now raises aSessionInterrupted
exception instead ofSuspiciousOperation
when a session is destroyed in a concurrent request.The
django.db.models.Field
equality operator now correctly distinguishes inherited field instances across models. Additionally, the ordering of such fields is now defined.The undocumented
django.core.files.locks.lock()
function now returnsFalse
if the file cannot be locked, instead of raisingBlockingIOError
.The password reset mechanism now invalidates tokens when the user email is changed.
makemessages
command no longer processes invalid locales specified usingmakemessages --locale
option, when they contain hyphens ('-'
).The
django.contrib.auth.forms.ReadOnlyPasswordHashField
form field is nowdisabled
by default. ThereforeUserChangeForm.clean_password()
is no longer required to return the initial value.The
cache.get_many()
,get_or_set()
,has_key()
,incr()
,decr()
,incr_version()
, anddecr_version()
cache operations now correctly handleNone
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 deprecatedMemcachedCache
backend.The minimum supported version of SQLite is increased from 3.8.3 to 3.9.0.
CookieStorage
now stores messages in the RFC 6265 compliant format. Support for cookies that use the old format remains until Django 4.1.The minimum supported version of
asgiref
is increased from 3.2.10 to 3.3.2.
Features deprecated in 3.2¶
Miscellaneous¶
- Assigning objects which don’t support creating deep copies with
copy.deepcopy()
to class attributes inTestCase.setUpTestData()
is deprecated. - Using a boolean value in
BaseCommand.requires_system_checks
is deprecated. Use'__all__'
instead ofTrue
, and[]
(an empty list) instead ofFalse
. - The
whitelist
argument anddomain_whitelist
attribute ofEmailValidator
are deprecated. Useallowlist
instead ofwhitelist
, anddomain_allowlist
instead ofdomain_whitelist
. You may need to renamewhitelist
in existing migrations. - The
default_app_config
application configuration variable is deprecated, due to the now automaticAppConfig
discovery. See What’s new in Django 3.2 for more details. - Automatically calling
repr()
on a queryset inTransactionTestCase.assertQuerysetEqual()
, when compared to string values, is deprecated. If you need the previous behavior, explicitly settransform
torepr
. - The
django.core.cache.backends.memcached.MemcachedCache
backend is deprecated aspython-memcached
has some problems and seems to be unmaintained. Usedjango.core.cache.backends.memcached.PyMemcacheCache
ordjango.core.cache.backends.memcached.PyLibMCCache
instead. - 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.