Django 6.0 and 6.1: what's new and how to plan the upgrade

Django versions and support dates

Every Django version has two support periods. During mainstream support it gets bug fixes; during extended support it gets only security fixes and fixes for data-loss bugs. Every third version is an LTS with roughly three years of support.

Dates from djangoproject.com/download and the Python version table in the Django documentation. Python 3.15 is supported from Django 6.1.3.

A new release cycle from 2028

Until now a new Django version came out roughly every 8 months. Django 6.2 will be the last version under this scheme. From 2028 versions will be released every January and named after the year: Django 2028, Django 2029 and so on. Each will get the same three-year support period, so the LTS label is no longer needed.

For a system owner this is simpler: a Django upgrade can be planned once a year at a fixed time, and there is no choice to make between an LTS and the latest version. The Django team recommends upgrading one version at a time.

Background tasks as standard

Sending emails, generating reports or importing files should not hold up the response to the user. Until now every project solved this its own way, most often with Celery. Django 6.0 adds a common API for defining and queuing tasks (django.tasks):

# settings.py (development)
TASKS = {"default": {"BACKEND": "django.tasks.backends.immediate.ImmediateBackend"}}

# tasks.py
from django.core.mail import send_mail
from django.tasks import task

@task(priority=2, queue_name="emails")
def email_users(emails, subject, message):
    return send_mail(subject=subject, message=message, from_email=None, recipient_list=emails)

# in a view
result = email_users.enqueue(emails=["jane@example.com"], subject="Hello", message="...")

An important caveat: Django does not include a process that runs the tasks (a worker). The two built-in backends, ImmediateBackend and DummyBackend, are meant for development and testing only. Production needs a backend from a third-party library, with a worker and a durable queue. Existing solutions such as Celery keep working. The common API is most useful in new projects and in libraries that no longer have to assume a particular queue.

A task queued inside a transaction is best enqueued only after the transaction commits (transaction.on_commit), so the worker does not look for data that is not in the database yet.

Template partials and HTMX

Django 6.0 brought the popular django-template-partials library into core. A fragment defined with {% partialdef %} can be used many times in the same template or rendered on its own by giving its name after a #:

{% partialdef user-info inline %}
  <div id="user-info-{{ user.username }}">
    <h3>{{ user.name }}</h3>
  </div>
{% endpartialdef %}

{% for user in featured %}
  {% partial user-info %}
{% endfor %}

# the view returns just the fragment, for example for an HTMX request
return render(request, "authors.html#user-info", {"user": user})

This matters for applications that use HTMX instead of a large JavaScript frontend: the whole page and the parts that refresh live in one template file, instead of being split into dozens of small files. For many business and public-sector systems this approach is entirely sufficient. We cover it in more detail in our React or Angular comparison.

Built-in Content Security Policy

Content Security Policy is a header that tells the browser where a page may load scripts, styles and images from. Set up well, it limits the damage from XSS attacks: even if someone injects a script, the browser will not run it. A missing CSP header is a common finding in application penetration test reports. Until now Django needed a third-party library for this; from version 6.0 CSP support is built in:

# settings.py
from django.utils.csp import CSP

MIDDLEWARE = [
    # ...
    "django.middleware.csp.ContentSecurityPolicyMiddleware",
]

SECURE_CSP = {
    "default-src": [CSP.SELF],
    "script-src": [CSP.SELF, CSP.NONCE],
    "img-src": [CSP.SELF, "https:"],
}

<script nonce="{{ csp_nonce }}">...</script>

The one-time nonce reaches templates through the django.template.context_processors.csp context processor. Django 6.1 added the {% csp_nonce_attr %} tag, and admin templates now get the nonce automatically. It is best to switch the policy on in report-only mode first (SECURE_CSP_REPORT_ONLY) and enforce it only after checking what it would block. Django does not collect violation reports, so you need a separate endpoint or service for that.

The ORM in Django 6.1: fetch modes and database-level deletes

The most common performance problem in Django applications is the N+1 query problem: a loop over a list of records that fetches a related object separately for each one. With a hundred records that is a hundred and one database queries. Until now you had to remember select_related() or prefetch_related(). Django 6.1 introduces field fetch modes:

from django.db import models

books = Book.objects.fetch_mode(models.FETCH_PEERS)
for book in books:
    print(book.author.name)  # 2 queries instead of one per book

• FETCH_ONE is the existing behaviour and still the default.
• FETCH_PEERS fetches a missing field for all records from the same query on first access, like an on-demand prefetch_related().
• FETCH_RAISE raises FieldFetchBlocked when code tries to load more data. It is useful in tests to catch N+1 problems before they reach production.

The second addition is deletion of related rows by the database. The DB_CASCADE, DB_SET_NULL and DB_SET_DEFAULT options become an SQL ON DELETE clause, so Django does not have to load every related object into memory before deleting:

class Comment(models.Model):
    post = models.ForeignKey(Post, on_delete=models.DB_CASCADE)

Limitations: with DB_CASCADE the pre_delete and post_delete signals do not fire for rows deleted this way, these options cannot be mixed with the regular ones (other than DO_NOTHING) in the same or related models, and DB_SET_DEFAULT needs db_default and does not work on MySQL or MariaDB.

Email and other changes

Email moved to the modern API of Python's standard library: EmailMessage.message() returns an email.message.EmailMessage object, and the old SafeMIMEText and SafeMIMEMultipart classes are deprecated. Optional arguments to the mail functions must be passed by keyword. Django 6.1 added the MAILERS setting, which lets you configure several mail servers, and the existing EMAIL_* settings are deprecated:

MAILERS = {
    "default": {
        "BACKEND": "django.core.mail.backends.smtp.EmailBackend",
        "OPTIONS": {"host": "smtp.example.com", "use_tls": True},
    },
}

Other changes worth knowing:

• DEFAULT_AUTO_FIELD now defaults to BigAutoField. Projects that relied on the implicit AutoField should set it explicitly to avoid unwanted migrations.
• AsyncPaginator and AsyncPage for pagination in asynchronous views.
• The StringAgg and AnyValue aggregates on every database backend, and in 6.1 also BitAnd, BitOr and BitXor plus the UUID4 and UUID7 functions.
• More PBKDF2 iterations for password hashing: 1.2 million in 6.0 and 1.5 million in 6.1.
• In 6.1, accessibility improvements to admin forms.

What to watch for when upgrading

Django 6.0

• Requires Python 3.12 or later. Applications on Python 3.10 and 3.11 must change their Python version first.
• Support for MariaDB 10.5 and the cx_Oracle driver is gone, and minimum versions of psycopg, Pillow and others went up.
• Removed: positional arguments to Model.save() and the check argument of CheckConstraint (now condition). forms.URLField assumes https.
• Custom Field.pre_save() implementations may be called more than once.

Django 6.1

• Minimum database versions: PostgreSQL 15, MySQL 8.4, MariaDB 10.11, SQLite 3.37.
• first() and last() after an empty order_by() no longer order by primary key.
• Aliases in generated SQL are always quoted, so raw queries that use mixed-case aliases may need fixes.
• Cache keys for pages and template fragments have changed. After deployment the cache fills up from scratch, which briefly increases load.
• Deprecated: the EMAIL_* settings and select_related() without arguments.

Wagtail: which version for which Django

For sites built on Wagtail, the CMS decides the Django version. Wagtail releases a new version every 3 months and an LTS every few releases. Wagtail 7.0 LTS, the last version for Django 4.2, reached end of support on 2 November 2026.

From the Wagtail release notes and release schedule. The next LTS is planned for May 2027.

For a site that should run steadily without frequent changes, we currently recommend Wagtail 7.4 LTS with Django 5.2 LTS. Django 6.1 requires Wagtail 8.0 or later, which are versions without long-term support that need upgrading every few months.

How to plan the upgrade

The Django documentation recommends upgrading step by step through each feature release, each time to its latest patch release. This also applies when moving from one LTS to the next. Deprecation warnings are fixed before changing version, because the deprecated features disappear in the next one.

1. Starting pointThe versions of Django, Python, the database and every library. We check which libraries are abandoned and what can replace them.
2. WarningsRunning tests with python -Wa manage.py test shows every deprecated call. We fix them while still on the current version.
3. One version at a timeOne version per step, reading the release notes and running the full test suite after each. Dependent libraries are upgraded together with Django.
4. Test environmentA copy of production data, migrations, background jobs, email sending, exports and integrations.
5. DeploymentA database backup before migrations, a rollback plan and log monitoring after deployment. With the cache key change we expect a short spike in load.

• Applications on Django 4.2 and older moved to 5.2 LTS first.
• Python 3.12 or later before moving to Django 6.
• PostgreSQL 15 or later (or MySQL 8.4, MariaDB 10.11) before moving to Django 6.1.
• No deprecation warnings in the test run.
• An explicit DEFAULT_AUTO_FIELD in settings.
• For Wagtail sites, a CMS version that matches the target Django.
• A fixed date for the yearly upgrade in the maintenance plan, in line with the new release cycle.

Frequently asked questions

Sources

• Django 6.0 release notes
• Django 6.1 release notes
• Django: supported versions and support dates
• Django: supported Python versions
• Django: upgrading to a newer version
• Django: background tasks (django.tasks)
• Wagtail 8.1 release notes
• Wagtail: release and support schedule

As of 6 November 2026. Dates of future Django and Wagtail versions are planned and may change.