December 3, 2025
\nWelcome to Django 6.0!
\nThese release notes cover the new features, as well as\nsome backwards incompatible changes you\nshould be aware of when upgrading from Django 5.2 or earlier. We’ve\nbegun the deprecation process for some features.
\nSee the How to upgrade Django to a newer version guide if you’re updating an existing\nproject.
\nDjango 6.0 supports Python 3.12, 3.13, and 3.14. We highly recommend, and\nonly officially support, the latest release of each series.
\nThe Django 5.2.x series is the last to support Python 3.10 and 3.11.
\nFollowing the release of Django 6.0, we suggest that third-party app authors\ndrop support for all versions of Django prior to 5.2. At that time, you should\nbe able to run your package’s tests using python -Wd so that deprecation\nwarnings appear. After making the deprecation warning fixes, your app should be\ncompatible with Django 6.0.
Built-in support for the Content Security Policy (CSP)\nstandard is now available, making it easier to protect web applications against\ncontent injection attacks such as cross-site scripting (XSS). CSP allows\ndeclaring trusted sources of content by giving browsers strict rules about\nwhich scripts, styles, images, or other resources can be loaded.
\nCSP policies can now be enforced or monitored directly using built-in tools:\nheaders are added via the\nContentSecurityPolicyMiddleware, nonces are\nsupported through the csp() context\nprocessor, and policies are configured using the SECURE_CSP and\nSECURE_CSP_REPORT_ONLY settings.
These settings accept Python dictionaries and support Django-provided constants\nfor clarity and safety. For example:
\nfrom django.utils.csp import CSP\n\nSECURE_CSP = {\n "default-src": [CSP.SELF],\n "script-src": [CSP.SELF, CSP.NONCE],\n "img-src": [CSP.SELF, "https:"],\n}\nThe resulting Content-Security-Policy header would be set to:
default-src 'self'; script-src 'self' 'nonce-SECRET'; img-src 'self' https:\nTo get started, follow the CSP how-to guide. For in-depth\nguidance, see the CSP security overview and the\nreference docs, which include details about decorators to\noverride or disable policies on a per-view basis.
\nThe Django Template Language now supports\ntemplate partials, making it easier to encapsulate\nand reuse small named fragments within a template file. The new tags\n{% partialdef %} and {% partial %}\ndefine a partial and render it, respectively.
Partials can also be referenced using the template_name#partial_name syntax\nwith get_template(),\nrender(), {% include %}, and other\ntemplate-loading tools, enabling more modular and maintainable templates\nwithout needing to split components into separate files.
A migration guide is available if you’re updating from the\ndjango-template-partials third-party package.
\nDjango now includes a built-in Tasks framework for running code outside the\nHTTP request–response cycle. This enables offloading work, such as sending\nemails or processing data, to background workers.
\nThe framework provides task definition, validation, queuing, and result\nhandling. Django guarantees consistent behavior for creating and managing\ntasks, while the responsibility for running them continues to belong to\nexternal worker processes.
\nTasks are defined using the task() decorator:
from django.core.mail import send_mail\nfrom django.tasks import task\n\n\n@task\ndef email_users(emails, subject, message):\n return send_mail(subject, message, None, emails)\nOnce defined, tasks can be enqueued through a configured backend:
\nemail_users.enqueue(\n emails=["user@example.com"],\n subject="You have a message",\n message="Hello there!",\n)\nBackends are configured via the TASKS setting. The two\nbuilt-in backends included in this release are\nprimarily intended for development and testing.
Django handles task creation and queuing, but does not provide a worker\nmechanism to run tasks. Execution must be managed by external infrastructure,\nsuch as a separate process or service.
\nSee Django’s Tasks framework for an overview and the Tasks reference for API details.
\nEmail handling in Django now uses Python’s modern email API, introduced in\nPython 3.6. This API, centered around the\nemail.message.EmailMessage class, offers a cleaner and\nUnicode-friendly interface for composing and sending emails. It replaces use of\nPython’s older legacy (Compat32) API, which relied on lower-level MIME\nclasses (from email.mime) and required more manual handling of\nmessage structure and encoding.
Notably, the return type of the EmailMessage.message() method is now an instance of Python’s\nemail.message.EmailMessage. This supports the same API as the\nprevious SafeMIMEText and SafeMIMEMultipart return types, but is not an\ninstance of those now-deprecated classes.
django.contrib.adminLink to this heading#The Font Awesome Free icon set (version 6.7.2) is now used for the admin\ninterface icons.
The new AdminSite.password_change_form attribute allows customizing\nthe form used in the admin site password change view.
Message levels messages.DEBUG and messages.INFO now have distinct\nicons and CSS styling. Previously, both levels shared the same appearance as\nmessages.SUCCESS. Given that ModelAdmin.message_user() uses\nmessages.INFO by default, set the level to messages.SUCCESS to keep\nthe previous icon and styling.
django.contrib.authLink to this heading#The default iteration count for the PBKDF2 password hasher is increased from\n1,000,000 to 1,200,000.
django.contrib.gisLink to this heading#The new GEOSGeometry.hasm property checks whether the geometry has\nthe M dimension.
The new Rotate database\nfunction rotates a geometry by a specified angle around the origin or a\nspecified point.
The new BaseGeometryWidget.base_layer attribute allows specifying a\nJavaScript map base layer, enabling customization of map tile providers.
coveredby and isvalid lookups,\nCollect aggregation, and\nGeoHash and\nIsValid database functions\nare now supported on MariaDB 12.0.1+.
The new geom_type lookup and\nGeometryType()\ndatabase function allow filtering geometries by their types.
Widgets from django.contrib.gis.forms.widgets now render without\ninline JavaScript in templates. If you have customized any geometry widgets\nor their templates, you may need to update them to match the new layout.
django.contrib.postgresLink to this heading#The new Lexeme expression\nfor full text search provides fine-grained control over search terms.\nLexeme objects automatically escape their input and support logical\ncombination operators (&, |, ~), prefix matching, and term\nweighting.
Model fields, indexes, and constraints from django.contrib.postgres\nnow include system checks to verify that django.contrib.postgres is an\ninstalled app.
The CreateExtension, BloomExtension,\nBtreeGinExtension, BtreeGistExtension,\nCITextExtension, CryptoExtension,\nHStoreExtension, TrigramExtension, and\nUnaccentExtension operations now support the optional hints\nparameter. This allows providing database hints to database routers to assist\nthem in making routing decisions.
django.contrib.staticfilesLink to this heading#ManifestStaticFilesStorage now\nensures consistent path ordering in manifest files, making them more\nreproducible and reducing unnecessary diffs.
The collectstatic command now reports only a summary for skipped\nfiles (and for deleted files when using --clear) at --verbosity 1. To\nsee per-file details for either case, set --verbosity to 2 or higher.
The new policy argument for EmailMessage.message() allows specifying the email policy,\nthe set of rules for updating and serializing the representation of the\nmessage. Defaults to email.policy.default.
EmailMessage.attach() now\naccepts a MIMEPart object from Python’s modern email\nAPI.
Added support and translations for the Haitian Creole language.
The startproject and startapp commands now create the\ncustom target directory if it doesn’t exist.
Common utilities, such as django.conf.settings, are now automatically\nimported to the shell by default.
Squashed migrations can now themselves be squashed before being transitioned\nto normal migrations.
Migrations now support serialization of zoneinfo.ZoneInfo instances.
Serialization of deconstructible objects now supports keyword arguments with\nnames that are not valid Python identifiers.
Constraints now implement a check()\nmethod that is already registered with the check framework.
The new order_by argument for Aggregate allows\nspecifying the ordering of the elements in the result.
The new Aggregate.allow_order_by class attribute determines whether\nthe aggregate function allows passing an order_by keyword argument.
The new StringAgg aggregate returns the input\nvalues concatenated into a string, separated by the delimiter string.\nThis aggregate was previously supported only for PostgreSQL.
The save() method now raises a specialized\nModel.NotUpdated exception, when\na forced update results in no affected rows,\ninstead of a generic django.db.DatabaseError.
QuerySet.raw() now supports models with a\nCompositePrimaryKey.
Subqueries returning a CompositePrimaryKey can now\nbe used as the target of lookups other than __in, such as __exact.
JSONField now supports\nnegative array indexing on SQLite.
The new AnyValue aggregate returns an arbitrary\nvalue from the non-null input values. This is supported on SQLite, MySQL,\nOracle, and PostgreSQL 16+.
GeneratedFields and fields assigned\nexpressions are now refreshed from the\ndatabase after save() on backends that support\nthe RETURNING clause (SQLite, PostgreSQL, and Oracle). On backends that\ndon’t support it (MySQL and MariaDB), the fields are marked as deferred to\ntrigger a refresh on subsequent accesses.
Using a ForeignObject with multiple\nfrom_fields in Model indexes, constraints, or unique_together now emits a system check error.
The new AsyncPaginator and\nAsyncPage provide async implementations of\nPaginator and\nPage respectively.
Multiple Cookie headers are now supported for HTTP/2 requests when\nrunning with ASGI.
The new variable forloop.length is now available within a for\nloop.
The querystring template tag now consistently prefixes the returned\nquery string with a ?, ensuring reliable link generation behavior.
The querystring template tag now accepts multiple positional\narguments, which must be mappings, such as QueryDict\nor dict.
The DiscoverRunner now supports parallel test execution on systems\nusing the forkserver multiprocessing start method.
This section describes changes that may be needed in third-party database\nbackends.
\nBaseDatabaseSchemaEditor and\nPostgreSQL backends no longer use CASCADE when dropping a column.
DatabaseOperations.return_insert_columns() and\nDatabaseOperations.fetch_returned_insert_rows() methods are renamed to\nreturning_columns() and fetch_returned_rows(), respectively, to\ndenote they can be used in the context of UPDATE … RETURNING statements\nas well as INSERT … RETURNING.
The DatabaseOperations.fetch_returned_insert_columns() method is removed\nand the fetch_returned_rows() method replacing\nfetch_returned_insert_rows() expects both a cursor and\nreturning_params to be provided, just like\nfetch_returned_insert_columns() did.
If the database supports UPDATE … RETURNING statements, backends can set\nDatabaseFeatures.can_return_rows_from_update=True.
Upstream support for MariaDB 10.5 ends in June 2025. Django 6.0 supports\nMariaDB 10.6 and higher.
\nBecause Python 3.12 is now the minimum supported version for Django, any\noptional dependencies must also meet that requirement. The following versions\nof each library are the first to add or confirm compatibility with Python 3.12:
\naiosmtpd 1.4.5
argon2-cffi 23.1.0
bcrypt 4.1.1
docutils 0.22
geoip2 4.8.0
Pillow 10.1.0
mysqlclient 2.2.1
numpy 1.26.0
PyYAML 6.0.2
psycopg 3.1.12
psycopg2 2.9.9
redis-py 5.1.0
selenium 4.23.0
sqlparse 0.5.0
tblib 3.0.0
The undocumented mixed_subtype and alternative_subtype properties\nof EmailMessage and\nEmailMultiAlternatives are no longer supported.
The undocumented encoding property of\nEmailMessage no longer supports Python legacy\nemail.charset.Charset objects.
As the internal implementations of EmailMessage\nand EmailMultiAlternatives have changed\nsignificantly, closely examine any custom subclasses that rely on overriding\nundocumented, internal underscore methods.
DEFAULT_AUTO_FIELD setting now defaults to BigAutoFieldLink to this heading#Since Django 3.2, when the DEFAULT_AUTO_FIELD setting was added,\nthe default startproject template’s settings.py contained:
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"\nand the default startapp template’s AppConfig contained:
default_auto_field = "django.db.models.BigAutoField"\nAt that time, the default value of DEFAULT_AUTO_FIELD remained\ndjango.db.models.AutoField for backwards compatibility.
In Django 6.0, DEFAULT_AUTO_FIELD now defaults to\ndjango.db.models.BigAutoField and the aforementioned lines in the\nproject and app templates are removed.
Most projects shouldn’t be affected, since Django 3.2 has raised the system\ncheck warning models.W042 for projects that don’t set\nDEFAULT_AUTO_FIELD.
If you haven’t dealt with this warning by now, add\nDEFAULT_AUTO_FIELD = 'django.db.models.AutoField' to your project’s\nsettings, or default_auto_field = 'django.db.models.AutoField' to an app’s\nAppConfig, as needed.
Prior to Django 6.0, custom lookups and\ncustom expressions implementing the\nas_sql() method (and its supporting methods process_lhs() and\nprocess_rhs()) were allowed to return a sequence of params in either a list\nor a tuple. To address the interoperability problems that resulted, the second\nreturn element of the as_sql() method should now be a tuple:
def as_sql(self, compiler, connection) -> tuple[str, tuple]: ...\nIf your custom expressions support multiple versions of Django, you should\nadjust any pre-processing of parameters to be resilient against either tuples\nor lists. For instance, prefer unpacking like this:
\nparams = (*lhs_params, *rhs_params)\nThe JSON serializer now writes a newline\nat the end of the output, even without the indent option set.
The minimum supported version of asgiref is increased from 3.8.1 to\n3.9.1.
Field.pre_save() may now be called more than once when saving model\ninstances, so custom implementations should be idempotent and free of side\neffects.
django.core.mail APIsLink to this heading#django.core.mail APIs now require keyword arguments for less commonly\nused parameters. Using positional arguments for these now emits a deprecation\nwarning and will raise a TypeError when the deprecation period ends:
All optional parameters (fail_silently and later) must be passed as\nkeyword arguments to get_connection(), mail_admins(),\nmail_managers(), send_mail(), and send_mass_mail().
All parameters must be passed as keyword arguments when creating an\nEmailMessage or EmailMultiAlternatives instance, except\nfor the first four (subject, body, from_email, and to), which\nmay still be passed either as positional or keyword arguments.
BaseDatabaseCreation.create_test_db(serialize) is deprecated. Use\nserialize_db_to_string() instead.
The PostgreSQL StringAgg class is deprecated in favor of the generally\navailable StringAgg class.
Passing a string to the\ndelimiter argument of\nthe (deprecated) PostgreSQL StringAgg class is deprecated. Use a\nValue or expression instead to prepare for\ncompatibility with the generally available\nStringAgg class.
The PostgreSQL OrderableAggMixin is deprecated in favor of the\norder_by attribute now available on the\nAggregate class.
The default protocol in urlize and urlizetrunc will\nchange from HTTP to HTTPS in Django 2028. Set the transitional setting\nURLIZE_ASSUME_HTTPS to True to opt into assuming HTTPS during\nthe Django 6.x release cycle.
The URLIZE_ASSUME_HTTPS transitional setting is deprecated.
Setting ADMINS or MANAGERS to a list of (name, address)\ntuples is deprecated. Set to a list of email address strings instead. Django\nnever used the name portion. To include a name, format the address string as\n'"Name" <address>' or use Python’s email.utils.formataddr().
Support for the orphans argument being larger than or equal to the\nper_page argument of django.core.paginator.Paginator and\ndjango.core.paginator.AsyncPaginator is deprecated.
Using a percent sign in a column alias or annotation is deprecated.
Support for passing Python’s legacy email MIMEBase\nobject to\nEmailMessage.attach() (or\nincluding one in the message’s attachments list) is deprecated. For\ncomplex attachments requiring additional headers or parameters, switch to the\nmodern email API’s MIMEPart.
The django.core.mail.BadHeaderError exception is deprecated. Python’s\nmodern email raises a ValueError for email headers containing\nprohibited characters.
The django.core.mail.SafeMIMEText and SafeMIMEMultipart classes are\ndeprecated.
The undocumented django.core.mail.forbid_multi_line_headers() and\ndjango.core.mail.message.sanitize_address() functions are deprecated.
These features have reached the end of their deprecation cycle and are removed\nin Django 6.0.
\nSee Features deprecated in 5.0 for details on these changes, including how\nto remove usage of these features.
\nSupport for passing positional arguments to BaseConstraint is removed.
The DjangoDivFormRenderer and Jinja2DivFormRenderer transitional form\nrenderers are removed.
BaseDatabaseOperations.field_cast_sql() is removed.
request is required in the signature of ModelAdmin.lookup_allowed()\nsubclasses.
Support for calling format_html() without passing args or kwargs is\nremoved.
The default scheme for forms.URLField has changed from "http" to\n"https".
The FORMS_URLFIELD_ASSUME_HTTPS transitional setting is removed.
The django.db.models.sql.datastructures.Join no longer falls back to\nget_joining_columns().
The get_joining_columns() method of ForeignObject and\nForeignObjectRel is removed.
The ForeignObject.get_reverse_joining_columns() method is removed.
Support for cx_Oracle is removed.
The ChoicesMeta alias to django.db.models.enums.ChoicesType is\nremoved.
The Prefetch.get_current_queryset() method is removed.
The get_prefetch_queryset() method of related managers and descriptors is\nremoved.
get_prefetcher() and prefetch_related_objects() no longer fall back\nto get_prefetch_queryset().
See Features deprecated in 5.1 for details on these changes, including how\nto remove usage of these features.
\ndjango.urls.register_converter() no longer allows overriding existing\nconverters.
The ModelAdmin.log_deletion() and LogEntryManager.log_action()\nmethods are removed.
The undocumented django.utils.itercompat.is_iterable() function and the\ndjango.utils.itercompat module are removed.
The django.contrib.gis.geoip2.GeoIP2.coords() method is removed.
The django.contrib.gis.geoip2.GeoIP2.open() method is removed.
Support for passing positional arguments to Model.save() and\nModel.asave() is removed.
The setter for django.contrib.gis.gdal.OGRGeometry.coord_dim is removed.
The check keyword argument of CheckConstraint is removed.
The get_cache_name() method of FieldCacheMixin is removed.
The OS_OPEN_FLAGS attribute of\nFileSystemStorage is removed.