============================================ Django 5.0 release notes - UNDER DEVELOPMENT ============================================ *Expected December 2023* Welcome to Django 5.0! These release notes cover the :ref:`new features `, as well as some :ref:`backwards incompatible changes ` you'll want to be aware of when upgrading from Django 4.2 or earlier. We've :ref:`begun the deprecation process for some features `. See the :doc:`/howto/upgrade-version` guide if you're updating an existing project. Python compatibility ==================== Django 5.0 supports Python 3.10, 3.11, and 3.12. We **highly recommend** and only officially support the latest release of each series. The Django 4.2.x series is the last to support Python 3.8 and 3.9. Third-party library support for older version of Django ======================================================= Following the release of Django 5.0, we suggest that third-party app authors drop support for all versions of Django prior to 4.2. At that time, you should be able to run your package's tests using ``python -Wd`` so that deprecation warnings appear. After making the deprecation warning fixes, your app should be compatible with Django 5.0. .. _whats-new-5.0: What's new in Django 5.0 ======================== Facet filters in the admin -------------------------- Facet counts are now shown for applied filters in the admin changelist when toggled on via the UI. This behavior can be changed via the new :attr:`.ModelAdmin.show_facets` attribute. For more information see :ref:`facet-filters`. Simplified templates for form field rendering --------------------------------------------- Django 5.0 introduces the concept of a field group, and field group templates. This simplifies rendering of the related elements of a Django form field such as its label, widget, help text, and errors. For example, the template below: .. code-block:: html+django
...
{{ form.name.label_tag }} {% if form.name.help_text %}
{{ form.name.help_text|safe }}
{% endif %} {{ form.name.errors }} {{ form.name }}
{{ form.email.label_tag }} {% if form.email.help_text %}
{{ form.email.help_text|safe }}
{% endif %} {{ form.email.errors }} {{ form.email }}
{{ form.password.label_tag }} {% if form.password.help_text %}
{{ form.password.help_text|safe }}
{% endif %} {{ form.password.errors }} {{ form.password }}
...
Can now be simplified to: .. code-block:: html+django
...
{{ form.name.as_field_group }}
{{ form.email.as_field_group }}
{{ form.password.as_field_group }}
...
:meth:`~django.forms.BoundField.as_field_group` renders fields with the ``"django/forms/field.html"`` template by default and can be customized on a per-project, per-field, or per-request basis. See :ref:`reusable-field-group-templates`. Database-computed default values -------------------------------- The new :attr:`Field.db_default ` parameter sets a database-computed default value. For example:: from django.db import models from django.db.models.functions import Now, Pi class MyModel(models.Model): age = models.IntegerField(db_default=18) created = models.DateTimeField(db_default=Now()) circumference = models.FloatField(db_default=2 * Pi()) Minor features -------------- :mod:`django.contrib.admin` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :meth:`.AdminSite.get_log_entries` method allows customizing the queryset for the site's listed log entries. * The ``django.contrib.admin.AllValuesFieldListFilter``, ``ChoicesFieldListFilter``, ``RelatedFieldListFilter``, and ``RelatedOnlyFieldListFilter`` admin filters now handle multi-valued query parameters. * ``XRegExp`` is upgraded from version 3.2.0 to 5.1.1. * The new :meth:`.AdminSite.get_model_admin` method returns an admin class for the given model class. :mod:`django.contrib.admindocs` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.auth` ~~~~~~~~~~~~~~~~~~~~~~~~~~ * The default iteration count for the PBKDF2 password hasher is increased from 600,000 to 720,000. * The new asynchronous functions are now provided, using an ``a`` prefix: :func:`django.contrib.auth.aauthenticate`, :func:`~.django.contrib.auth.aget_user`, :func:`~.django.contrib.auth.alogin`, :func:`~.django.contrib.auth.alogout`, and :func:`~.django.contrib.auth.aupdate_session_auth_hash`. * ``AuthenticationMiddleware`` now adds an :meth:`.HttpRequest.auser` asynchronous method that returns the currently logged-in user. * The new :func:`django.contrib.auth.hashers.acheck_password` asynchronous function and :meth:`.AbstractBaseUser.acheck_password` method allow asynchronous checking of user passwords. :mod:`django.contrib.contenttypes` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.gis` ~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :class:`ClosestPoint() ` function returns a 2-dimensional point on the geometry that is closest to another geometry. * :ref:`GIS aggregates ` now support the ``filter`` argument. * Added support for GDAL 3.7. * Added support for GEOS 3.12. * The new :meth:`.GEOSGeometry.equals_identical` method allows point-wise equivalence checking of geometries. :mod:`django.contrib.messages` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.postgres` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * The new :attr:`~.ExclusionConstraint.violation_error_code` attribute of :class:`~django.contrib.postgres.constraints.ExclusionConstraint` allows customizing the ``code`` of ``ValidationError`` raised during :ref:`model validation `. :mod:`django.contrib.redirects` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.sessions` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.sitemaps` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.sites` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.staticfiles` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... :mod:`django.contrib.syndication` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * ... Asynchronous views ~~~~~~~~~~~~~~~~~~ * Under ASGI, ``http.disconnect`` events are now handled. This allows views to perform any necessary cleanup if a client disconnects before the response is generated. See :ref:`async-handling-disconnect` for more details. Cache ~~~~~ * ... CSRF ~~~~ * ... Decorators ~~~~~~~~~~ * The following decorators now support wrapping asynchronous view functions: * :func:`~django.views.decorators.cache.cache_control` * :func:`~django.views.decorators.cache.never_cache` * :func:`~django.views.decorators.common.no_append_slash` * :func:`~django.views.decorators.csrf.csrf_exempt` * :func:`~django.views.decorators.debug.sensitive_variables` * :func:`~django.views.decorators.debug.sensitive_post_parameters` * :func:`~django.views.decorators.http.condition` * :func:`~django.views.decorators.http.etag` * :func:`~django.views.decorators.http.last_modified` * :func:`~django.views.decorators.http.require_http_methods` * :func:`~django.views.decorators.http.require_GET` * :func:`~django.views.decorators.http.require_POST` * :func:`~django.views.decorators.http.require_safe` * :func:`~django.views.decorators.vary.vary_on_cookie` * :func:`~django.views.decorators.vary.vary_on_headers` * ``xframe_options_deny()`` * ``xframe_options_sameorigin()`` * ``xframe_options_exempt()`` Email ~~~~~ * ... Error Reporting ~~~~~~~~~~~~~~~ * :func:`~django.views.decorators.debug.sensitive_variables` and :func:`~django.views.decorators.debug.sensitive_post_parameters` can now be used with asynchronous functions. File Storage ~~~~~~~~~~~~ * ... File Uploads ~~~~~~~~~~~~ * ... Forms ~~~~~ * :attr:`.ChoiceField.choices` now accepts :ref:`Choices classes ` directly instead of requiring expansion with the ``choices`` attribute. * The new ``assume_scheme`` argument for :class:`~django.forms.URLField` allows specifying a default URL scheme. * In order to improve accessibility and enable screen readers to associate form fields with their help text, the form field now includes the ``aria-describedby`` HTML attribute. * In order to improve accessibility, the invalid form field now includes the ``aria-invalid="true"`` HTML attribute. Generic Views ~~~~~~~~~~~~~ * ... Internationalization ~~~~~~~~~~~~~~~~~~~~ * Added support and translations for the Uyghur language. Logging ~~~~~~~ * ... Management Commands ~~~~~~~~~~~~~~~~~~~ * ... Migrations ~~~~~~~~~~ * ... Models ~~~~~~ * The new ``create_defaults`` argument of :meth:`.QuerySet.update_or_create` and :meth:`.QuerySet.aupdate_or_create` methods allows specifying a different field values for the create operation. * The new ``violation_error_code`` attribute of :class:`~django.db.models.BaseConstraint`, :class:`~django.db.models.CheckConstraint`, and :class:`~django.db.models.UniqueConstraint` allows customizing the ``code`` of ``ValidationError`` raised during :ref:`model validation `. * :attr:`.Field.choices` now accepts :ref:`Choices classes ` directly instead of requiring expansion with the ``choices`` attribute. * The :ref:`force_insert ` argument of :meth:`.Model.save` now allows specifying a tuple of parent classes that must be forced to be inserted. * :meth:`.QuerySet.bulk_create` and :meth:`.QuerySet.abulk_create` methods now set the primary key on each model instance when the ``update_conflicts`` parameter is enabled (if the database supports it). * The new :attr:`.UniqueConstraint.nulls_distinct` attribute allows customizing the treatment of ``NULL`` values on PostgreSQL 15+. * The new :func:`~django.shortcuts.aget_object_or_404` and :func:`~django.shortcuts.aget_list_or_404` asynchronous shortcuts allow asynchronous getting objects. * The new :func:`~django.db.models.aprefetch_related_objects` function allows asynchronous prefetching of model instances. * :meth:`.QuerySet.aiterator` now supports previous calls to ``prefetch_related()``. * On MariaDB 10.7+, ``UUIDField`` is now created as ``UUID`` column rather than ``CHAR(32)`` column. See the migration guide above for more details on :ref:`migrating-uuidfield`. * Django now supports `oracledb`_ version 1.3.2 or higher. Support for ``cx_Oracle`` is deprecated as of this release and will be removed in Django 6.0. Pagination ~~~~~~~~~~ * The new :attr:`django.core.paginator.Paginator.error_messages` argument allows customizing the error messages raised by :meth:`.Paginator.page`. Requests and Responses ~~~~~~~~~~~~~~~~~~~~~~ * ... Security ~~~~~~~~ * ... Serialization ~~~~~~~~~~~~~ * ... Signals ~~~~~~~ * The new :meth:`.Signal.asend` and :meth:`.Signal.asend_robust` methods allow asynchronous signal dispatch. Signal receivers may be synchronous or asynchronous, and will be automatically adapted to the correct calling style. Templates ~~~~~~~~~ * The new :tfilter:`escapeseq` template filter applies :tfilter:`escape` to each element of a sequence. Tests ~~~~~ * :class:`~django.test.Client` and :class:`~django.test.AsyncClient` now provide asynchronous methods, using an ``a`` prefix: :meth:`~django.test.Client.asession`, :meth:`~django.test.Client.alogin`, :meth:`~django.test.Client.aforce_login`, and :meth:`~django.test.Client.alogout`. URLs ~~~~ * ... Utilities ~~~~~~~~~ * ... Validators ~~~~~~~~~~ * The new ``offset`` argument of :class:`~django.core.validators.StepValueValidator` allows specifying an offset for valid values. .. _backwards-incompatible-5.0: Backwards incompatible changes in 5.0 ===================================== Database backend API -------------------- This section describes changes that may be needed in third-party database backends. * ``DatabaseFeatures.supports_expression_defaults`` should be set to ``False`` if the database doesn't support using database functions as defaults. * ``DatabaseFeatures.supports_default_keyword_in_insert`` should be set to ``False`` if the database doesn't support the ``DEFAULT`` keyword in ``INSERT`` queries. * ``DatabaseFeatures.supports_default_keyword_in_bulk insert`` should be set to ``False`` if the database doesn't support the ``DEFAULT`` keyword in bulk ``INSERT`` queries. Dropped support for MySQL < 8.0.11 ---------------------------------- Support for pre-releases of MySQL 8.0.x series is removed. Django 5.0 supports MySQL 8.0.11 and higher. :mod:`django.contrib.gis` ------------------------- * Support for GDAL 2.2 and 2.3 is removed. * Support for GEOS 3.6 and 3.7 is removed. :mod:`django.contrib.sitemaps` ------------------------------ * The ``django.contrib.sitemaps.ping_google()`` function and the ``ping_google`` management command are removed as the Google Sitemaps ping endpoint is deprecated and will be removed in January 2024. * The ``django.contrib.sitemaps.SitemapNotFound`` exception class is removed. Using ``create_defaults__exact`` may now be required with ``QuerySet.update_or_create()`` ----------------------------------------------------------------------------------------- :meth:`.QuerySet.update_or_create` now supports the parameter ``create_defaults``. As a consequence, any models that have a field named ``create_defaults`` that are used with an ``update_or_create()`` should specify the field in the lookup with ``create_defaults__exact``. .. _migrating-uuidfield: Migrating existing ``UUIDField`` on MariaDB 10.7+ ------------------------------------------------- On MariaDB 10.7+, ``UUIDField`` is now created as ``UUID`` column rather than ``CHAR(32)`` column. As a consequence, any ``UUIDField`` created in Django < 5.0 should be replaced with a ``UUIDField`` subclass backed by ``CHAR(32)``:: class Char32UUIDField(models.UUIDField): def db_type(self, connection): return "char(32)" For example:: class MyModel(models.Model): uuid = models.UUIDField(primary_key=True, default=uuid.uuid4) Should become:: class Char32UUIDField(models.UUIDField): def db_type(self, connection): return "char(32)" class MyModel(models.Model): uuid = Char32UUIDField(primary_key=True, default=uuid.uuid4) Running the :djadmin:`makemigrations` command will generate a migration containing a no-op ``AlterField`` operation. Miscellaneous ------------- * The ``instance`` argument of the undocumented ``BaseModelFormSet.save_existing()`` method is renamed to ``obj``. * The undocumented ``django.contrib.admin.helpers.checkbox`` is removed. * Integer fields are now validated as 64-bit integers on SQLite to match the behavior of ``sqlite3``. * The undocumented ``Query.annotation_select_mask`` attribute is changed from a set of strings to an ordered list of strings. * ``ImageField.update_dimension_fields()`` is no longer called on the ``post_init`` signal if ``width_field`` and ``height_field`` are not set. * :class:`~django.db.models.functions.Now` database function now uses ``LOCALTIMESTAMP`` instead of ``CURRENT_TIMESTAMP`` on Oracle. * :attr:`.AdminSite.site_header` is now rendered in a ``
`` tag instead of ``

``. Screen reader users rely on heading elements for navigation within a page. Having two ``

`` elements was confusing and the site header wasn't helpful as it is repeated on all pages. * On databases without native support for the SQL ``XOR`` operator, ``^`` as the exclusive or (``XOR``) operator now returns rows that are matched by an odd number of operands rather than exactly one operand. This is consistent with the behavior of MySQL, MariaDB, and Python. * The minimum supported version of ``asgiref`` is increased from 3.6.0 to 3.7.0. * The minimum supported version of ``selenium`` is increased from 3.8.0 to 4.8.0. * The ``AlreadyRegistered`` and ``NotRegistered`` exceptions are moved from ``django.contrib.admin.sites`` to ``django.contrib.admin.exceptions``. * The minimum supported version of SQLite is increased from 3.21.0 to 3.27.0. * Support for ``cx_Oracle`` < 8.3 is removed. * Executing SQL queries before the app registry has been fully populated now raises :exc:`RuntimeWarning`. .. _deprecated-features-5.0: Features deprecated in 5.0 ========================== Miscellaneous ------------- * The ``DjangoDivFormRenderer`` and ``Jinja2DivFormRenderer`` transitional form renderers are deprecated. * Passing positional arguments ``name`` and ``violation_error_message`` to :class:`~django.db.models.BaseConstraint` is deprecated in favor of keyword-only arguments. * ``request`` is added to the signature of :meth:`.ModelAdmin.lookup_allowed`. Support for ``ModelAdmin`` subclasses that do not accept this argument is deprecated. * The ``get_joining_columns()`` method of ``ForeignObject`` and ``ForeignObjectRel`` is deprecated. Starting with Django 6.0, ``django.db.models.sql.datastructures.Join`` will no longer fallback to ``get_joining_columns()``. Subclasses should implement ``get_joining_fields()`` instead. * The ``ForeignObject.get_reverse_joining_columns()`` method is deprecated. * The default scheme for ``forms.URLField`` will change from ``"http"`` to ``"https"`` in Django 6.0. * Support for calling ``format_html()`` without passing args or kwargs will be removed. * Support for ``cx_Oracle`` is deprecated in favor of `oracledb`_ 1.3.2+ Python driver. .. _`oracledb`: https://oracle.github.io/python-oracledb/ Features removed in 5.0 ======================= These features have reached the end of their deprecation cycle and are removed in Django 5.0. See :ref:`deprecated-features-4.0` for details on these changes, including how to remove usage of these features. * The ``SERIALIZE`` test setting is removed. * The undocumented ``django.utils.baseconv`` module is removed. * The undocumented ``django.utils.datetime_safe`` module is removed. * The default value of the ``USE_TZ`` setting is changed from ``False`` to ``True``. * The default sitemap protocol for sitemaps built outside the context of a request is changed from ``'http'`` to ``'https'``. * The ``extra_tests`` argument for ``DiscoverRunner.build_suite()`` and ``DiscoverRunner.run_tests()`` is removed. * The ``django.contrib.postgres.aggregates.ArrayAgg``, ``JSONBAgg``, and ``StringAgg`` aggregates no longer return ``[]``, ``[]``, and ``''``, respectively, when there are no rows. * The ``USE_L10N`` setting is removed. * The ``USE_DEPRECATED_PYTZ`` transitional setting is removed. * Support for ``pytz`` timezones is removed. * The ``is_dst`` argument is removed from: * ``QuerySet.datetimes()`` * ``django.utils.timezone.make_aware()`` * ``django.db.models.functions.Trunc()`` * ``django.db.models.functions.TruncSecond()`` * ``django.db.models.functions.TruncMinute()`` * ``django.db.models.functions.TruncHour()`` * ``django.db.models.functions.TruncDay()`` * ``django.db.models.functions.TruncWeek()`` * ``django.db.models.functions.TruncMonth()`` * ``django.db.models.functions.TruncQuarter()`` * ``django.db.models.functions.TruncYear()`` * The ``django.contrib.gis.admin.GeoModelAdmin`` and ``OSMGeoAdmin`` classes are removed. * The undocumented ``BaseForm._html_output()`` method is removed. * The ability to return a ``str``, rather than a ``SafeString``, when rendering an ``ErrorDict`` and ``ErrorList`` is removed. See :ref:`deprecated-features-4.1` for details on these changes, including how to remove usage of these features. * The ``SitemapIndexItem.__str__()`` method is removed. * The ``CSRF_COOKIE_MASKED`` transitional setting is removed. * The ``name`` argument of ``django.utils.functional.cached_property()`` is removed. * The ``opclasses`` argument of ``django.contrib.postgres.constraints.ExclusionConstraint`` is removed. * The undocumented ability to pass ``errors=None`` to ``SimpleTestCase.assertFormError()`` and ``assertFormsetError()`` is removed. * ``django.contrib.sessions.serializers.PickleSerializer`` is removed. * The usage of ``QuerySet.iterator()`` on a queryset that prefetches related objects without providing the ``chunk_size`` argument is no longer allowed. * Passing unsaved model instances to related filters is no longer allowed. * ``created=True`` is required in the signature of ``RemoteUserBackend.configure_user()`` subclasses. * Support for logging out via ``GET`` requests in the ``django.contrib.auth.views.LogoutView`` and ``django.contrib.auth.views.logout_then_login()`` is removed. * The ``django.utils.timezone.utc`` alias to ``datetime.timezone.utc`` is removed. * Passing a response object and a form/formset name to ``SimpleTestCase.assertFormError()`` and ``assertFormSetError()`` is no longer allowed. * The ``django.contrib.gis.admin.OpenLayersWidget`` is removed. + The ``django.contrib.auth.hashers.CryptPasswordHasher`` is removed. * The ``"django/forms/default.html"`` and ``"django/forms/formsets/default.html"`` templates are removed. * The default form and formset rendering style is changed to the div-based. * Passing ``nulls_first=False`` or ``nulls_last=False`` to ``Expression.asc()`` and ``Expression.desc()`` methods, and the ``OrderBy`` expression is no longer allowed.