{"title":"Django 3.2 release notes","version":"dev","locale":"en","docname":"releases/3.2","url":"/en/dev/releases/3.2/","canonical":"https://djangodocs.dev/en/dev/releases/3.2/","summary":"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…","html":"

Django 3.2 release notesLink to this heading#

\n

April 6, 2021

\n

Welcome to Django 3.2!

\n

These release notes cover the new features, as well as\nsome backwards incompatible changes you’ll\nwant to be aware of when upgrading from Django 3.1 or earlier. We’ve\nbegun the deprecation process for some features.

\n

See the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.

\n

Django 3.2 is designated as a long-term support release. It will receive security updates for at least\nthree years after its release. Support for the previous LTS, Django 2.2, will\nend in April 2022.

\n
\n

Python compatibilityLink to this heading#

\n

Django 3.2 supports Python 3.6, 3.7, 3.8, 3.9, and 3.10 (as of 3.2.9). We\nhighly recommend and only officially support the latest release of each\nseries.

\n
\n
\n

What’s new in Django 3.2Link to this heading#

\n
\n

Automatic AppConfig discoveryLink to this heading#

\n

Most pluggable applications define an AppConfig subclass\nin an apps.py submodule. Many define a default_app_config variable\npointing to this class in their __init__.py.

\n

When the apps.py submodule exists and defines a single\nAppConfig subclass, Django now uses that configuration\nautomatically, so you can remove default_app_config.

\n

default_app_config made it possible to declare only the application’s path\nin INSTALLED_APPS (e.g. 'django.contrib.admin') rather than the\napp config’s path (e.g. 'django.contrib.admin.apps.AdminConfig'). It was\nintroduced for backwards-compatibility with the former style, with the intent\nto switch the ecosystem to the latter, but the switch didn’t happen.

\n

With automatic AppConfig discovery, default_app_config is no longer\nneeded. As a consequence, it’s deprecated.

\n

See Configuring applications for full details.

\n
\n
\n

Customizing type of auto-created primary keysLink to this heading#

\n

When defining a model, if no field in a model is defined with\nprimary_key=True an implicit\nprimary key is added. The type of this implicit primary key can now be\ncontrolled via the DEFAULT_AUTO_FIELD setting and\nAppConfig.default_auto_field\nattribute. No more needing to override primary keys in all models.

\n

Maintaining the historical behavior, the default value for\nDEFAULT_AUTO_FIELD is AutoField. Starting\nwith 3.2 new projects are generated with DEFAULT_AUTO_FIELD set to\nBigAutoField. Also, new apps are generated with\nAppConfig.default_auto_field\nset to BigAutoField. In a future Django release the\ndefault value of DEFAULT_AUTO_FIELD will be changed to\nBigAutoField.

\n

To avoid unwanted migrations in the future, either explicitly set\nDEFAULT_AUTO_FIELD to AutoField:

\n
Code
DEFAULT_AUTO_FIELD = "django.db.models.AutoField"\n
\n

or configure it on a per-app basis:

\n
Code
from django.apps import AppConfig\n\n\nclass MyAppConfig(AppConfig):\n    default_auto_field = "django.db.models.AutoField"\n    name = "my_app"\n
\n

or on a per-model basis:

\n
Code
from django.db import models\n\n\nclass MyModel(models.Model):\n    id = models.AutoField(primary_key=True)\n
\n

In anticipation of the changing default, a system check will provide a warning\nif you do not have an explicit setting for DEFAULT_AUTO_FIELD.

\n

When changing the value of DEFAULT_AUTO_FIELD, migrations for the\nprimary key of existing auto-created through tables cannot be generated\ncurrently. See the DEFAULT_AUTO_FIELD docs for details on migrating\nsuch tables.

\n
\n
\n

Functional indexesLink to this heading#

\n

The new *expressions positional\nargument of Index() enables creating\nfunctional indexes on expressions and database functions. For example:

\n
Code
from django.db import models\nfrom django.db.models import F, Index, Value\nfrom django.db.models.functions import Lower, Upper\n\n\nclass MyModel(models.Model):\n    first_name = models.CharField(max_length=255)\n    last_name = models.CharField(max_length=255)\n    height = models.IntegerField()\n    weight = models.IntegerField()\n\n    class Meta:\n        indexes = [\n            Index(\n                Lower("first_name"),\n                Upper("last_name").desc(),\n                name="first_last_name_idx",\n            ),\n            Index(\n                F("height") / (F("weight") + Value(5)),\n                name="calc_idx",\n            ),\n        ]\n
\n

Functional indexes are added to models using the\nMeta.indexes option.

\n
\n
\n

pymemcache supportLink to this heading#

\n

The new django.core.cache.backends.memcached.PyMemcacheCache cache backend\nallows using the pymemcache library for memcached. pymemcache 3.4.0\nor higher is required. For more details, see the documentation on caching\nin Django.

\n
\n
\n

New decorators for the admin siteLink to this heading#

\n

The new display() decorator allows for easily\nadding options to custom display functions that can be used with\nlist_display or\nreadonly_fields.

\n

Likewise, the new action() decorator allows for\neasily adding options to action functions that can be used with\nactions.

\n

Using the @display decorator has the advantage that it is now\npossible to use the @property decorator when needing to specify attributes\non the custom method. Prior to this it was necessary to use the property()\nfunction instead after assigning the required attributes to the method.

\n

Using decorators has the advantage that these options are more discoverable as\nthey can be suggested by completion utilities in code editors. They are merely\na convenience and still set the same attributes on the functions under the\nhood.

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

  • ModelAdmin.search_fields now allows searching against quoted phrases\nwith spaces.

    • \n

  • Read-only related fields are now rendered as navigable links if target models\nare registered in the admin.

    • \n

  • The admin now supports theming, and includes a dark theme that is enabled\naccording to browser settings. See Theming support for more details.

    • \n

  • ModelAdmin.autocomplete_fields now respects\nForeignKey.to_field and\nForeignKey.limit_choices_to when searching a related\nmodel.

    • \n

  • The admin now installs a final catch-all view that redirects unauthenticated\nusers to the login page, regardless of whether the URL is otherwise valid.\nThis protects against a potential model enumeration privacy issue.

    \n

    Although not recommended, you may set the new\nAdminSite.final_catch_all_view to False to disable the\ncatch-all view.

    \n
    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n
    \n

  • The default iteration count for the PBKDF2 password hasher is increased from\n216,000 to 260,000.

    • \n

  • The default variant for the Argon2 password hasher is changed to Argon2id.\nmemory_cost and parallelism are increased to 102,400 and 8\nrespectively to match the argon2-cffi defaults.

    \n

    Increasing the memory_cost pushes the required memory from 512 KB to 100\nMB. This is still rather conservative but can lead to problems in memory\nconstrained environments. If this is the case, the existing hasher can be\nsubclassed to override the defaults.

    \n
    • \n

  • The default salt entropy for the Argon2, MD5, PBKDF2, SHA-1 password hashers\nis increased from 71 to 128 bits.

    • \n
\n
\n
\n

django.contrib.contenttypesLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

django.contrib.postgresLink to this heading#

\n
    \n

  • The new ExclusionConstraint.include attribute allows creating\ncovering exclusion constraints on PostgreSQL 12+.

    • \n

  • The new ExclusionConstraint.opclasses attribute allows setting PostgreSQL\noperator classes.

    • \n

  • The new JSONBAgg.ordering attribute determines the ordering of the\naggregated elements.

    • \n

  • The new JSONBAgg.distinct attribute determines if aggregated values\nwill be distinct.

    • \n

  • The CreateExtension operation\nnow checks that the extension already exists in the database and skips the\nmigration if so.

    • \n

  • The new CreateCollation and\nRemoveCollation operations\nallow creating and dropping collations on PostgreSQL. See\nManaging collations using migrations for more details.

    • \n

  • Lookups for ArrayField now allow\n(non-nested) arrays containing expressions as right-hand sides.

    • \n

  • The new OpClass()\nexpression allows creating functional indexes on expressions with a custom\noperator class. See Functional indexes for more details.

    • \n
\n
\n
\n

django.contrib.sitemapsLink to this heading#

\n\n
\n
\n

django.contrib.syndicationLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

Database backendsLink to this heading#

\n
    \n

  • Third-party database backends can now skip or mark as expected failures\ntests in Django’s test suite using the new\nDatabaseFeatures.django_test_skips and\ndjango_test_expected_failures attributes.

    • \n
\n
\n
\n

DecoratorsLink to this heading#

\n\n
\n
\n

Error ReportingLink to this heading#

\n\n
\n
\n

File UploadsLink to this heading#

\n\n
\n
\n

FormsLink to this heading#

\n\n
\n
\n

Generic ViewsLink to this heading#

\n\n
\n
\n

Management CommandsLink to this heading#

\n
    \n

  • loaddata now supports fixtures stored in XZ archives (.xz) and\nLZMA archives (.lzma).

    • \n

  • dumpdata now can compress data in the bz2, gz, lzma,\nor xz formats.

    • \n

  • makemigrations can now be called without an active database\nconnection. In that case, check for a consistent migration history is\nskipped.

    • \n

  • BaseCommand.requires_system_checks now supports specifying a list of\ntags. System checks registered in the chosen tags will be checked for errors\nprior to executing the command. In previous versions, either all or none\nof the system checks were performed.

    • \n

  • Support for colored terminal output on Windows is updated. Various modern\nterminal environments are automatically detected, and the options for\nenabling support in other cases are improved. See Syntax coloring for\nmore details.

    • \n
\n
\n
\n

MigrationsLink to this heading#

\n
    \n

  • The new Operation.migration_name_fragment property allows providing a\nfilename fragment that will be used to name a migration containing only that\noperation.

    • \n

  • Migrations now support serialization of pure and concrete path objects from\npathlib, and os.PathLike instances.

    • \n
\n
\n
\n

ModelsLink to this heading#

\n
    \n

  • The new no_key parameter for QuerySet.select_for_update(),\nsupported on PostgreSQL, allows acquiring weaker locks that don’t block the\ncreation of rows that reference locked rows through a foreign key.

    • \n

  • When() expression now allows\nusing the condition argument with lookups.

    • \n

  • The new Index.include and UniqueConstraint.include\nattributes allow creating covering indexes and covering unique constraints on\nPostgreSQL 11+.

    • \n

  • The new UniqueConstraint.opclasses attribute allows setting\nPostgreSQL operator classes.

    • \n

  • The QuerySet.update() method now respects the order_by() clause on\nMySQL and MariaDB.

    • \n

  • FilteredRelation() now supports\nnested relations.

    • \n

  • The of argument of QuerySet.select_for_update() is now allowed\non MySQL 8.0.1+.

    • \n

  • Value() expression now\nautomatically resolves its output_field to the appropriate\nField subclass based on the type of\nits provided value for bool, bytes,\nfloat, int, str,\ndatetime.date, datetime.datetime,\ndatetime.time, datetime.timedelta,\ndecimal.Decimal, and uuid.UUID instances. As a\nconsequence, resolving an output_field for database functions and\ncombined expressions may now crash with mixed types when using Value().\nYou will need to explicitly set the output_field in such cases.

    • \n

  • The new QuerySet.alias() method allows creating reusable aliases for\nexpressions that don’t need to be selected but are used for filtering,\nordering, or as a part of complex expressions.

    • \n

  • The new Collate function allows\nfiltering and ordering by specified database collations.

    • \n

  • The field_name argument of QuerySet.in_bulk() now accepts\ndistinct fields if there’s only one field specified in\nQuerySet.distinct().

    • \n

  • The new tzinfo parameter of the\nTruncDate and\nTruncTime database functions allows\ntruncating datetimes in a specific timezone.

    • \n

  • The new db_collation argument for\nCharField and\nTextField allows setting a\ndatabase collation for the field.

    • \n

  • Added the Random database function.

    • \n

  • Aggregation functions, F(),\nOuterRef(), and other expressions now\nallow using transforms. See Expressions can reference transforms for\ndetails.

    • \n

  • The new durable argument for atomic()\nguarantees that changes made in the atomic block will be committed if the\nblock exits without errors. A nested atomic block marked as durable will\nraise a RuntimeError.

    • \n

  • Added the JSONObject database function.

    • \n
\n
\n
\n

PaginationLink to this heading#

\n\n
\n
\n

Requests and ResponsesLink to this heading#

\n\n
\n
\n

SecurityLink to this heading#

\n\n
\n
\n

SerializationLink to this heading#

\n
    \n

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

    • \n
\n
\n
\n

SignalsLink to this heading#

\n\n
\n
\n

TemplatesLink to this heading#

\n\n
\n
\n

TestsLink to this heading#

\n\n
\n
\n

UtilitiesLink to this heading#

\n
    \n

  • The new depth parameter of django.utils.timesince.timesince() and\ndjango.utils.timesince.timeuntil() functions allows specifying the number\nof adjacent time units to return.

    • \n
\n
\n
\n

ValidatorsLink to this heading#

\n
    \n

  • Built-in validators now include the provided value in the params argument\nof a raised ValidationError. This allows\ncustom error messages to use the %(value)s placeholder.

    • \n

  • The ValidationError equality operator now ignores messages and\nparams ordering.

    • \n
\n
\n
\n
\n
\n

Backwards incompatible changes in 3.2Link to this heading#

\n
\n

Database backend APILink to this heading#

\n

This section describes changes that may be needed in third-party database\nbackends.

\n\n
\n
\n

django.contrib.adminLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n\n
\n
\n

Dropped support for PostgreSQL 9.5Link to this heading#

\n

Upstream support for PostgreSQL 9.5 ends in February 2021. Django 3.2 supports\nPostgreSQL 9.6 and higher.

\n
\n
\n

Dropped support for MySQL 5.6Link to this heading#

\n

The end of upstream support for MySQL 5.6 is April 2021. Django 3.2 supports\nMySQL 5.7 and higher.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 3.2Link to this heading#

\n
\n

MiscellaneousLink to this heading#

\n\n
\n
","rootId":"django-3-2-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"What’s new in Django 3.2","anchor":"what-s-new-in-django-3-2","children":[{"title":"Automatic AppConfig discovery","anchor":"automatic-appconfig-discovery","children":[]},{"title":"Customizing type of auto-created primary keys","anchor":"customizing-type-of-auto-created-primary-keys","children":[]},{"title":"Functional indexes","anchor":"functional-indexes","children":[]},{"title":"pymemcache support","anchor":"pymemcache-support","children":[]},{"title":"New decorators for the admin site","anchor":"new-decorators-for-the-admin-site","children":[]},{"title":"Minor features","anchor":"minor-features","children":[{"title":"django.contrib.admin","anchor":"django-contrib-admin","children":[]},{"title":"django.contrib.auth","anchor":"django-contrib-auth","children":[]},{"title":"django.contrib.contenttypes","anchor":"django-contrib-contenttypes","children":[]},{"title":"django.contrib.gis","anchor":"django-contrib-gis","children":[]},{"title":"django.contrib.postgres","anchor":"django-contrib-postgres","children":[]},{"title":"django.contrib.sitemaps","anchor":"django-contrib-sitemaps","children":[]},{"title":"django.contrib.syndication","anchor":"django-contrib-syndication","children":[]},{"title":"Database backends","anchor":"database-backends","children":[]},{"title":"Decorators","anchor":"decorators","children":[]},{"title":"Error Reporting","anchor":"error-reporting","children":[]},{"title":"File Uploads","anchor":"file-uploads","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Generic Views","anchor":"generic-views","children":[]},{"title":"Management Commands","anchor":"management-commands","children":[]},{"title":"Migrations","anchor":"migrations","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Pagination","anchor":"pagination","children":[]},{"title":"Requests and Responses","anchor":"requests-and-responses","children":[]},{"title":"Security","anchor":"security","children":[]},{"title":"Serialization","anchor":"serialization","children":[]},{"title":"Signals","anchor":"signals","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"Utilities","anchor":"utilities","children":[]},{"title":"Validators","anchor":"validators","children":[]}]}]},{"title":"Backwards incompatible changes in 3.2","anchor":"backwards-incompatible-changes-in-3-2","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.admin","anchor":"id1","children":[]},{"title":"django.contrib.gis","anchor":"id2","children":[]},{"title":"Dropped support for PostgreSQL 9.5","anchor":"dropped-support-for-postgresql-9-5","children":[]},{"title":"Dropped support for MySQL 5.6","anchor":"dropped-support-for-mysql-5-6","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 3.2","anchor":"features-deprecated-in-3-2","children":[{"title":"Miscellaneous","anchor":"id3","children":[]}]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/3.2.1","title":"Django 3.2.1 release notes","url":"/en/dev/releases/3.2.1/"},"next":{"docname":"releases/3.1.14","title":"Django 3.1.14 release notes","url":"/en/dev/releases/3.1.14/"},"formats":{"html":"/en/dev/releases/3.2/","markdown":"/en/dev/releases/3.2.md","json":"/en/dev/releases/3.2.json"},"source":"https://github.com/django/django/blob/main/docs/releases/3.2.txt","official":"https://docs.djangoproject.com/en/dev/releases/3.2/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2"],"inLocales":["en"]}