• Language: en
  • Documentation version: development

Django 3.2 release notes - UNDER DEVELOPMENT

Expected April 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 Upgrading 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, and 3.8. 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.

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.

Minor features

django.contrib.admin

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 and parallelism are increased to 102,400 and 8 respectively to match the argon2-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.

django.contrib.contenttypes

django.contrib.postgres

django.contrib.sitemaps

django.contrib.syndication

  • The new item_comments hook allows specifying a comments URL per feed item.

Cache

CSRF

Email

Error Reporting

File Storage

File Uploads

Forms

Generic Views

Internationalization

Logging

Management Commands

  • loaddata now supports fixtures stored in XZ archives (.xz) and LZMA archives (.lzma).
  • 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.

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, and os.PathLike instances.

Models

  • The new no_key parameter for QuerySet.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 the condition argument with lookups.
  • The new Index.include and UniqueConstraint.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 the order_by() clause on MySQL and MariaDB.
  • FilteredRelation() now supports nested relations.
  • The 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 it’s provided value for bool, bytes, float, int, str, datetime.date, datetime.datetime, datetime.time, datetime.timedelta, decimal.Decimal, and uuid.UUID instances. As a consequence, resolving an output_field for database functions and combined expressions may now crash with mixed types when using Value(). You will need to explicitly set the output_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 of QuerySet.in_bulk() now accepts distinct fields if there’s only one field specified in QuerySet.distinct().
  • The new tzinfo parameter of the TruncDate and TruncTime database functions allows truncating datetimes in a specific timezone.
  • The new db_collation argument for CharField and TextField allows setting a database collation for the field.

Pagination

Requests and Responses

  • Response headers are now stored in HttpResponse.headers. This can be used instead of the original dict-like interface of HttpResponse objects. Both interfaces will continue to be supported. See Setting header fields for details.

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 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 raise an ImproperlyConfigured exception.

Serialization

  • The new JSONL serializer allows using the JSON Lines format with dumpdata and loaddata. This can be useful for populating large databases because data is loaded line by line into memory, rather than being loaded all at once.

Signals

Templates

Tests

URLs

Utilities

  • The new depth parameter of django.utils.timesince.timesince() and django.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 raised ValidationError. This allows custom error messages to use the %(value)s placeholder.
  • The ValidationError equality operator now ignores messages and params 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), set DatabaseFeatures.supports_covering_indexes to True.
  • Third-party database backends must implement support for column database collations on CharFields and TextFields or set DatabaseFeatures.supports_collation_on_charfield and DatabaseFeatures.supports_collation_on_textfield to False. If non-deterministic collations are not supported, set supports_non_deterministic_collations to False.

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.

django.contrib.gis

  • Support for PostGIS 2.2 is removed.

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

  • The undocumented SpatiaLiteOperations.proj4_version() method is renamed to proj_version().
  • 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'.
  • slugify() now removes leading and trailing dashes and underscores.
  • The intcomma and intword template filters no longer depend on the USE_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 an apps.py submodule, Django now uses this configuration automatically, even if it isn’t enabled with default_app_config. Set default = False in the 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 TypeError.
  • Keyword arguments to setup_databases() are now keyword-only.
  • The undocumented django.utils.http.limited_parse_qsl() function is removed. Please use urllib.parse.parse_qsl() instead.
  • django.test.utils.TestContextDecorator now uses addCleanup() so that cleanups registered in the setUp() method are called before TestContextDecorator.disable().
  • SessionMiddleware now raises a SessionInterrupted exception instead of SuspiciousOperation 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 returns False if the file cannot be locked, instead of raising BlockingIOError.

Features deprecated in 3.2

Miscellaneous

  • Assigning objects which don’t support creating deep copies with copy.deepcopy() to class attributes in TestCase.setUpTestData() is deprecated.
  • Using a boolean value in BaseCommand.requires_system_checks is deprecated. Use '__all__' instead of True, and [] (an empty list) instead of False.
  • The whitelist argument and domain_whitelist attribute of EmailValidator are deprecated. Use allowlist instead of whitelist, and domain_allowlist instead of domain_whitelist. You may need to rename whitelist in existing migrations.
  • The 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.
Back to Top