{"title":"Django 5.0 release notes","version":"dev","locale":"en","docname":"releases/5.0","url":"/en/dev/releases/5.0/","canonical":"https://djangodocs.dev/en/dev/releases/5.0/","summary":"Welcome to Django 5.0! 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 5.0 release notesLink to this heading#

\n

December 4, 2023

\n

Welcome to Django 5.0!

\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 4.2 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
\n

Python compatibilityLink to this heading#

\n

Django 5.0 supports Python 3.10, 3.11, and 3.12. We highly recommend and\nonly officially support the latest release of each series.

\n

The Django 4.2.x series is the last to support Python 3.8 and 3.9.

\n
\n
\n

Third-party library support for older version of DjangoLink to this heading#

\n

Following the release of Django 5.0, we suggest that third-party app authors\ndrop support for all versions of Django prior to 4.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 5.0.

\n
\n
\n

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

\n
\n

Facet filters in the adminLink to this heading#

\n

Facet counts are now shown for applied filters in the admin changelist when\ntoggled on via the UI. This behavior can be changed via the new\nModelAdmin.show_facets attribute. For more information see\nFacets.

\n
\n
\n

Simplified templates for form field renderingLink to this heading#

\n

Django 5.0 introduces the concept of a field group, and field group templates.\nThis simplifies rendering of the related elements of a Django form field such\nas its label, widget, help text, and errors.

\n

For example, the template below:

\n
Django template
<form>\n...\n<div>\n  {{ form.name.label_tag }}\n  {% if form.name.help_text %}\n    <div class="helptext" id="{{ form.name.auto_id }}_helptext">\n      {{ form.name.help_text|safe }}\n    </div>\n  {% endif %}\n  {{ form.name.errors }}\n  {{ form.name }}\n  <div class="row">\n    <div class="col">\n      {{ form.email.label_tag }}\n      {% if form.email.help_text %}\n        <div class="helptext" id="{{ form.email.auto_id }}_helptext">\n          {{ form.email.help_text|safe }}\n        </div>\n      {% endif %}\n      {{ form.email.errors }}\n      {{ form.email }}\n    </div>\n    <div class="col">\n      {{ form.password.label_tag }}\n      {% if form.password.help_text %}\n        <div class="helptext" id="{{ form.password.auto_id }}_helptext">\n          {{ form.password.help_text|safe }}\n        </div>\n      {% endif %}\n      {{ form.password.errors }}\n      {{ form.password }}\n    </div>\n  </div>\n</div>\n...\n</form>\n
\n

Can now be simplified to:

\n
Django template
<form>\n...\n<div>\n  {{ form.name.as_field_group }}\n  <div class="row">\n    <div class="col">{{ form.email.as_field_group }}</div>\n    <div class="col">{{ form.password.as_field_group }}</div>\n  </div>\n</div>\n...\n</form>\n
\n

as_field_group() renders fields with the\n"django/forms/field.html" template by default and can be customized on a\nper-project, per-field, or per-request basis. See\nReusable field group templates.

\n
\n
\n

Database-computed default valuesLink to this heading#

\n

The new Field.db_default parameter\nsets a database-computed default value. For example:

\n
Code
from django.db import models\nfrom django.db.models.functions import Now, Pi\n\n\nclass MyModel(models.Model):\n    age = models.IntegerField(db_default=18)\n    created = models.DateTimeField(db_default=Now())\n    circumference = models.FloatField(db_default=2 * Pi())\n
\n
\n
\n

Database generated model fieldLink to this heading#

\n

The new GeneratedField allows creation of database\ngenerated columns. This field can be used on all supported database backends\nto create a field that is always computed from other fields. For example:

\n
Code
from django.db import models\nfrom django.db.models import F\n\n\nclass Square(models.Model):\n    side = models.IntegerField()\n    area = models.GeneratedField(\n        expression=F("side") * F("side"),\n        output_field=models.BigIntegerField(),\n        db_persist=True,\n    )\n
\n
\n
\n

More options for declaring field choicesLink to this heading#

\n

Field.choices (for model fields) and ChoiceField.choices\n(for form fields) allow for more flexibility when declaring their values. In\nprevious versions of Django, choices should either be a list of 2-tuples,\nor an Enumeration types subclass, but the latter required\naccessing the .choices attribute to provide the values in the expected\nform:

\n
Code
from django.db import models\n\nMedal = models.TextChoices("Medal", "GOLD SILVER BRONZE")\n\nSPORT_CHOICES = [\n    ("Martial Arts", [("judo", "Judo"), ("karate", "Karate")]),\n    ("Racket", [("badminton", "Badminton"), ("tennis", "Tennis")]),\n    ("unknown", "Unknown"),\n]\n\n\nclass Winner(models.Model):\n    name = models.CharField(...)\n    medal = models.CharField(..., choices=Medal.choices)\n    sport = models.CharField(..., choices=SPORT_CHOICES)\n
\n

Django 5.0 adds support for accepting a mapping or a callable instead of an\niterable, and also no longer requires .choices to be used directly to\nexpand enumeration types:

\n
Code
from django.db import models\n\nMedal = models.TextChoices("Medal", "GOLD SILVER BRONZE")\n\nSPORT_CHOICES = {  # Using a mapping instead of a list of 2-tuples.\n    "Martial Arts": {"judo": "Judo", "karate": "Karate"},\n    "Racket": {"badminton": "Badminton", "tennis": "Tennis"},\n    "unknown": "Unknown",\n}\n\n\ndef get_scores():\n    return [(i, str(i)) for i in range(10)]\n\n\nclass Winner(models.Model):\n    name = models.CharField(...)\n    medal = models.CharField(..., choices=Medal)  # Using `.choices` not required.\n    sport = models.CharField(..., choices=SPORT_CHOICES)\n    score = models.IntegerField(choices=get_scores)  # A callable is allowed.\n
\n

Under the hood the provided choices are normalized into a list of 2-tuples\nas the canonical form whenever the choices value is updated. For more\ninformation, please check the model field reference on choices.

\n
\n
\n

Minor featuresLink to this heading#

\n
\n

django.contrib.adminLink to this heading#

\n
    \n

  • The new AdminSite.get_log_entries() method allows customizing the\nqueryset for the site’s listed log entries.

    • \n

  • The django.contrib.admin.AllValuesFieldListFilter,\nChoicesFieldListFilter, RelatedFieldListFilter, and\nRelatedOnlyFieldListFilter admin filters now handle multi-valued query\nparameters.

    • \n

  • XRegExp is upgraded from version 3.2.0 to 5.1.1.

    • \n

  • The new AdminSite.get_model_admin() method returns an admin class for\nthe given model class.

    • \n

  • Properties in ModelAdmin.list_display now support boolean\nattribute.

    • \n

  • jQuery is upgraded from version 3.6.4 to 3.7.1.

    • \n
\n
\n
\n

django.contrib.authLink to this heading#

\n\n
\n
\n

django.contrib.contenttypesLink to this heading#

\n\n
\n
\n

django.contrib.gisLink to this heading#

\n
    \n

  • The new\nClosestPoint()\nfunction returns a 2-dimensional point on the geometry that is closest to\nanother geometry.

    • \n

  • GIS aggregates now support the filter\nargument.

    • \n

  • Support for GDAL 3.7 and GEOS 3.12 is added.

    • \n

  • The new GEOSGeometry.equals_identical() method allows point-wise\nequivalence checking of geometries.

    • \n
\n
\n
\n

django.contrib.messagesLink to this heading#

\n\n
\n
\n

django.contrib.postgresLink to this heading#

\n\n
\n
\n

Asynchronous viewsLink to this heading#

\n
    \n

  • Under ASGI, http.disconnect events are now handled. This allows views to\nperform any necessary cleanup if a client disconnects before the response is\ngenerated. See Handling disconnects for more details.

    • \n
\n
\n
\n

DecoratorsLink to this heading#

\n\n
\n
\n

Error ReportingLink to this heading#

\n\n
\n
\n

File StorageLink to this heading#

\n
    \n

  • File.open() now passes all positional (*args) and keyword\narguments (**kwargs) to Python’s built-in open().

    • \n
\n
\n
\n

FormsLink to this heading#

\n
    \n

  • The new assume_scheme argument for\nURLField allows specifying a default URL scheme.

    • \n

  • In order to improve accessibility, the following changes are made:

    \n
      \n

    • Form fields now include the aria-describedby HTML attribute to enable\nscreen readers to associate form fields with their help text.

      • \n

    • Invalid form fields now include the aria-invalid="true" HTML attribute.

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

InternationalizationLink to this heading#

\n
    \n

  • Support and translations for the Uyghur language are now available.

    • \n
\n
\n
\n

MigrationsLink to this heading#

\n\n
\n
\n

ModelsLink to this heading#

\n\n
\n
\n

PaginationLink to this heading#

\n\n
\n
\n

SignalsLink to this heading#

\n
    \n

  • The new Signal.asend() and Signal.asend_robust() methods allow\nasynchronous signal dispatch. Signal receivers may be synchronous or\nasynchronous, and will be automatically adapted to the correct calling style.

    • \n
\n
\n
\n

TemplatesLink to this heading#

\n
    \n

  • The new escapeseq template filter applies escape to\neach element of a sequence.

    • \n
\n
\n
\n

TestsLink to this heading#

\n\n
\n
\n

ValidatorsLink to this heading#

\n
    \n

  • The new offset argument of\nStepValueValidator allows specifying an\noffset for valid values.

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

Backwards incompatible changes in 5.0Link 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.gisLink to this heading#

\n\n
\n
\n

django.contrib.sitemapsLink to this heading#

\n\n
\n
\n

Dropped support for MySQL < 8.0.11Link to this heading#

\n

Support for pre-releases of MySQL 8.0.x series is removed. Django 5.0 supports\nMySQL 8.0.11 and higher.

\n
\n
\n

Using create_defaults__exact may now be required with QuerySet.update_or_create()Link to this heading#

\n

QuerySet.update_or_create() now supports the parameter\ncreate_defaults. As a consequence, any models that have a field named\ncreate_defaults that are used with an update_or_create() should specify\nthe field in the lookup with create_defaults__exact.

\n
\n
\n

Migrating existing UUIDField on MariaDB 10.7+Link to this heading#

\n

On MariaDB 10.7+, UUIDField is now created as UUID column rather than\nCHAR(32) column. As a consequence, any UUIDField created in\nDjango < 5.0 should be replaced with a UUIDField subclass backed by\nCHAR(32):

\n
Code
class Char32UUIDField(models.UUIDField):\n    def db_type(self, connection):\n        return "char(32)"\n\n    def get_db_prep_value(self, value, connection, prepared=False):\n        value = super().get_db_prep_value(value, connection, prepared)\n        if value is not None:\n            value = value.hex\n        return value\n
\n

For example:

\n
Code
class MyModel(models.Model):\n    uuid = models.UUIDField(primary_key=True, default=uuid.uuid4)\n
\n

Should become:

\n
Code
class Char32UUIDField(models.UUIDField): ...\n\n\nclass MyModel(models.Model):\n    uuid = Char32UUIDField(primary_key=True, default=uuid.uuid4)\n
\n

Running the makemigrations command will generate a migration\ncontaining a no-op AlterField operation.

\n
\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features deprecated in 5.0Link to this heading#

\n
\n

MiscellaneousLink to this heading#

\n\n
\n
\n
\n

Features removed in 5.0Link to this heading#

\n

These features have reached the end of their deprecation cycle and are removed\nin Django 5.0.

\n

See Features deprecated in 4.0 for details on these changes, including how\nto remove usage of these features.

\n\n

See Features deprecated in 4.1 for details on these changes, including how\nto remove usage of these features.

\n\n\n\n
","rootId":"django-5-0-release-notes","toc":[{"title":"Python compatibility","anchor":"python-compatibility","children":[]},{"title":"Third-party library support for older version of Django","anchor":"third-party-library-support-for-older-version-of-django","children":[]},{"title":"What’s new in Django 5.0","anchor":"what-s-new-in-django-5-0","children":[{"title":"Facet filters in the admin","anchor":"facet-filters-in-the-admin","children":[]},{"title":"Simplified templates for form field rendering","anchor":"simplified-templates-for-form-field-rendering","children":[]},{"title":"Database-computed default values","anchor":"database-computed-default-values","children":[]},{"title":"Database generated model field","anchor":"database-generated-model-field","children":[]},{"title":"More options for declaring field choices","anchor":"more-options-for-declaring-field-choices","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.messages","anchor":"django-contrib-messages","children":[]},{"title":"django.contrib.postgres","anchor":"django-contrib-postgres","children":[]},{"title":"Asynchronous views","anchor":"asynchronous-views","children":[]},{"title":"Decorators","anchor":"decorators","children":[]},{"title":"Error Reporting","anchor":"error-reporting","children":[]},{"title":"File Storage","anchor":"file-storage","children":[]},{"title":"Forms","anchor":"forms","children":[]},{"title":"Internationalization","anchor":"internationalization","children":[]},{"title":"Migrations","anchor":"migrations","children":[]},{"title":"Models","anchor":"models","children":[]},{"title":"Pagination","anchor":"pagination","children":[]},{"title":"Signals","anchor":"signals","children":[]},{"title":"Templates","anchor":"templates","children":[]},{"title":"Tests","anchor":"tests","children":[]},{"title":"Validators","anchor":"validators","children":[]}]}]},{"title":"Backwards incompatible changes in 5.0","anchor":"backwards-incompatible-changes-in-5-0","children":[{"title":"Database backend API","anchor":"database-backend-api","children":[]},{"title":"django.contrib.gis","anchor":"id1","children":[]},{"title":"django.contrib.sitemaps","anchor":"django-contrib-sitemaps","children":[]},{"title":"Dropped support for MySQL < 8.0.11","anchor":"dropped-support-for-mysql-8-0-11","children":[]},{"title":"Using create_defaults__exact may now be required with QuerySet.update_or_create()","anchor":"using-create-defaults-exact-may-now-be-required-with-queryset-update-or-create","children":[]},{"title":"Migrating existing UUIDField on MariaDB 10.7+","anchor":"migrating-existing-uuidfield-on-mariadb-10-7","children":[]},{"title":"Miscellaneous","anchor":"miscellaneous","children":[]}]},{"title":"Features deprecated in 5.0","anchor":"features-deprecated-in-5-0","children":[{"title":"Miscellaneous","anchor":"id2","children":[]}]},{"title":"Features removed in 5.0","anchor":"features-removed-in-5-0","children":[]}],"breadcrumbs":[{"docname":"releases/index","title":"Release notes","url":"/en/dev/releases/"}],"prev":{"docname":"releases/5.0.1","title":"Django 5.0.1 release notes","url":"/en/dev/releases/5.0.1/"},"next":{"docname":"releases/4.2.30","title":"Django 4.2.30 release notes","url":"/en/dev/releases/4.2.30/"},"formats":{"html":"/en/dev/releases/5.0/","markdown":"/en/dev/releases/5.0.md","json":"/en/dev/releases/5.0.json"},"source":"https://github.com/django/django/blob/main/docs/releases/5.0.txt","official":"https://docs.djangoproject.com/en/dev/releases/5.0/","inVersions":["dev","6.1","6.0","5.2","5.1","5.0"],"inLocales":["en"]}