Upgrading Django 4.2 to 5.2: The Safe Path and What Breaks at Each Step

MicroPyramid 13 min read
Upgrading Django 4.2 to 5.2: The Safe Path and What Breaks at Each Step

Short answer: move to the latest Django 4.2 patch release, run your tests with deprecation warnings switched on and fix every one, then move Python to 3.12 while you are still on 4.2. After that, step through Django 5.0, 5.1 and 5.2, each on its latest patch release, with the tests passing at every step. Test coverage and third-party packages drive most of the effort.

Django 4.2 LTS lost security support on April 7, 2026, and 4.2.30 is its final release. The natural target is Django 5.2, the current long-term support release, with security fixes until April 2028. What follows comes from Django's own release notes. For the other 2026 and 2027 deadlines, see our end-of-life guide.

Django 4.2 to 5.2 support matrix

Each release on the way changes which Python and database versions Django supports. Check this table against what you run before you plan anything else.

Django Python PostgreSQL MySQL MariaDB SQLite Security support ends
4.2 LTS 3.8 to 3.12 (3.12 from 4.2.8) 12 or newer 8 or newer 10.4 or newer 3.21.0 or newer April 7, 2026 (ended)
5.0 3.10 to 3.12 12 or newer 8.0.11 or newer 10.4 or newer 3.27.0 or newer April 2, 2025 (ended)
5.1 3.10 to 3.13 (3.13 from 5.1.3) 13 or newer 8.0.11 or newer 10.5 or newer 3.31.0 or newer December 3, 2025 (ended)
5.2 LTS 3.10 to 3.14 (3.14 from 5.2.8) 14 or newer 8.0.11 or newer 10.5 or newer 3.31.0 or newer April 2028

Sources: Django's Python version FAQ, release notes, databases reference and download page. Latest patch releases at the time of writing: 4.2.30, 5.0.14, 5.1.15 and 5.2.19.

What the table means in practice:

  • Python 3.12 is the newest version every step supports (from Django 4.2.8), so move Python first and leave it alone while Django moves.
  • Avoid Python 3.10. Django 5.2 still supports it, but it reached end of life on October 1, 2026.
  • Django 5.0 and 5.1 get no security fixes. They are stops on the way to 5.2, not places to stay.
  • Your database may need to move first. Django 5.1 needs PostgreSQL 13 and MariaDB 10.5, and Django 5.2 needs PostgreSQL 14.

Before you change Django: get 4.2 clean

Most upgrade surprises can be found and fixed while you are still on 4.2. None of this changes the Django version, so the risk is low.

  1. Move to the latest 4.2 patch release. Django keeps patch releases compatible with their feature release unless a security or data-loss fix makes that impossible.
  2. Make the tests trustworthy. Add tests around sign-in, payments, anything that writes data, and the admin screens your team relies on. If there are no tests at all, a few end-to-end checks on the critical paths are far better than none.
  3. Switch deprecation warnings on and fix them. Python hides them by default. Django's upgrade guide recommends running the tests with -Wa and resolving every warning before you move on. Warnings from inside third-party packages are not always a problem; the ones in your own code are your to-do list.
  4. Move Python to 3.12 on Django 4.2, and ship that as its own release. On Python 3.8 or 3.9 this step is required anyway: Django 5.0 needs Python 3.10 or newer.
# Stay on Django 4.2, but on its newest patch release
python -m pip install "Django~=4.2.0"

# Run the tests with deprecation warnings shown (Django test runner)
python -Wa manage.py test

# With pytest, also turn off output capture so the warnings are visible
PYTHONWARNINGS=always pytest tests --capture=no

Step 1: Django 4.2 to 5.0

This is usually the biggest step, because Django 5.0 removes everything deprecated in 4.0 and 4.1. If you fixed the warnings on 4.2, most of it is already done.

The changes that most often break real apps:

  • pytz support is removed. Django has defaulted to the standard library's zoneinfo since 4.0. The USE_DEPRECATED_PYTZ setting is gone, and so is the is_dst argument of timezone.make_aware(), QuerySet.datetimes() and the Trunc functions.
  • The USE_TZ default changes from False to True. If your settings never set it, your datetime handling changes on upgrade. Set it explicitly.
  • USE_L10N and the django.utils.timezone.utc alias are removed. Use datetime.timezone.utc instead.
  • Forms render as <div> markup by default. {{ form }} used to produce table-based output, and the old django/forms/default.html templates are removed. Templates, CSS and JavaScript that expect table rows need changing. The transitional DjangoDivFormRenderer is deprecated in 5.0 and removed in 6.0.
  • Logout needs a POST. LogoutView and logout_then_login() no longer accept GET, so logout links become small forms.
  • Old test assertion signatures are removed. assertFormError() and assertFormsetError() no longer accept a response and a form name. Pass the form itself, for example response.context["form"].
  • Smaller removals that still bite: the session PickleSerializer, QuerySet.iterator() on a query with prefetch_related() but no chunk_size, and unsaved model instances in related filters.
  • Database changes. MySQL 8.0.11 and SQLite 3.27.0 are the new minimums. On MariaDB 10.7 and newer, UUIDField becomes a native UUID column instead of CHAR(32), and the release notes show how to keep existing columns as they are.

Full list: Django 5.0 release notes.

# settings.py
# The USE_TZ default changed from False to True in Django 5.0.
# If your settings never set it, you have been running with False:
# pin that first, and move to aware datetimes as a separate change.
USE_TZ = False

# Removed in Django 5.0: delete these lines if they are still here.
# USE_L10N = True
# USE_DEPRECATED_PYTZ = True
# Before: pytz, no longer supported in Django 5.0
import pytz
london = pytz.timezone("Europe/London")

# After: the standard library
from zoneinfo import ZoneInfo
london = ZoneInfo("Europe/London")

# django.utils.timezone.utc is removed; use the standard library instead
from datetime import timezone
utc = timezone.utc
<!-- Logout needs a POST from Django 5.0 -->
<form method="post" action="{% url 'logout' %}">
  {% csrf_token %}
  <button type="submit">Log out</button>
</form>

Step 2: Django 5.0 to 5.1

Django 5.1 removes what 4.2 deprecated. The code replacements all exist in 4.2, so you can make most of these changes before the upgrade starts.

  • STORAGES replaces DEFAULT_FILE_STORAGE and STATICFILES_STORAGE, and get_storage_class() is gone. STORAGES is not merged with its default, so define both the default and staticfiles entries.
  • Meta.index_together is removed. Move it to Meta.indexes, and makemigrations generates a RenameIndex operation for the existing index. The 4.2 release notes also suggest squashing migrations to clear index_together out of old migration files.
  • Two test assertions are removed: assertQuerysetEqual() (now assertQuerySetEqual()) and assertFormsetError() (now assertFormSetError()).
  • The length_is template filter is removed. Write {% if value|length == 4 %} instead.
  • Old password hashers are removed: SHA1PasswordHasher, UnsaltedSHA1PasswordHasher and UnsaltedMD5PasswordHasher. If PASSWORD_HASHERS still lists them, decide how those accounts will sign in before this step.
  • CICharField, CIEmailField and CITextField are removed, except in historical migrations. Use a regular field with a case-insensitive db_collation.
  • Also removed: make_random_password() (use Python's secrets module), positional arguments to Signer and TimestampSigner, and JSON-encoded string literals passed to JSONField.
  • Database minimums rise to PostgreSQL 13, MariaDB 10.5 and SQLite 3.31.0.
  • Admin markup changes. The changelist filter, footer and collapsible fieldsets use new HTML elements, and collapse.js is gone. Check any admin templates and CSS you have overridden.

Full list: Django 5.1 release notes.

# Before: both settings are removed in Django 5.1
DEFAULT_FILE_STORAGE = "django.core.files.storage.FileSystemStorage"
STATICFILES_STORAGE = "django.contrib.staticfiles.storage.StaticFilesStorage"

# After: STORAGES exists since Django 4.2, so you can switch before upgrading.
# It is not merged with the default, so define both entries.
STORAGES = {
    "default": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}
# Before: Meta.index_together is removed in Django 5.1
class Author(models.Model):
    rank = models.IntegerField()
    name = models.CharField(max_length=30)

    class Meta:
        index_together = [["rank", "name"]]


# After: then run makemigrations, which renames the existing index
class Author(models.Model):
    rank = models.IntegerField()
    name = models.CharField(max_length=30)

    class Meta:
        indexes = [models.Index(fields=["rank", "name"])]

Step 3: Django 5.1 to 5.2

This is usually the lightest step. Django 5.2 removes no deprecated features (the next removals come in 6.0), but two database changes matter in production.

  • PostgreSQL 14 is the new minimum. Support for PostgreSQL 13 is dropped.
  • MySQL connections default to utf8mb4 instead of utf8, an alias for the deprecated utf8mb3. A legacy database that still needs utf8mb3 can set it in the database OPTIONS.
  • Aggregates are stricter. Avg, Count, Max, Min, StdDev, Sum and Variance raise TypeError when given the wrong number of arguments.
  • EmailMultiAlternatives accepts alternatives only through attach_alternative().
  • UniqueConstraint now always uses violation_error_code and violation_error_message when you provide them.

Keep the warnings on once you land. Django 5.2 deprecates the ordering argument of the PostgreSQL ArrayAgg, JSONBAgg and StringAgg aggregates (use order_by), and the deprecation timeline lists what 6.0 removes, including positional arguments to Model.save(), the check argument of CheckConstraint (now condition) and the transitional div form renderers. Clearing those now shrinks the later move to 6.2 LTS. Full list: Django 5.2 release notes.

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        # NAME, USER, PASSWORD and HOST as before.
        # Django 5.2 connects with utf8mb4 by default.
        # Only if a legacy database still needs the old character set:
        "OPTIONS": {"charset": "utf8mb3"},
    }
}

Third-party packages: check every dependency

Upgrades are more often blocked by a package than by Django itself. Check each dependency against the version you are moving to before you start that step.

  • See what is behind with pip list --outdated in your current environment.
  • Check support for the target version. On each package's PyPI page, look for the Framework :: Django :: 5.2 classifier (or 5.0 and 5.1 for the earlier steps), then confirm it in the changelog. Classifiers can go stale, so the changelog and your tests have the final word.
  • Use a clean environment for each step, as Django's upgrade guide suggests for a major upgrade. Pin Django, install your requirements, and run pip check to catch conflicts.
  • Find abandoned packages early. One with no Django 5 release and no recent activity needs a decision: a maintained alternative, a fork you patch yourself, or dropping the feature. This is often the largest single task.
# What is behind in the current environment?
python -m pip list --outdated

# A clean environment for the next step, with Django pinned in
# requirements.txt (Django~=5.0.0, then ~=5.1.0, then ~=5.2.0)
python -m venv .venv-next
source .venv-next/bin/activate
python -m pip install -r requirements.txt
python -m pip check

Tools that do the mechanical work

Two command-line tools handle most of the repetitive rewrites, and the test runner shows you what is left. Review their changes like any other pull request.

  • python -Wa manage.py test at every step, so new deprecation warnings show up straight away.
  • django-upgrade rewrites deprecated Django code. Its --target-version option takes a version such as 5.0 and enables every fixer up to and including it. It handles STORAGES, index_together, the renamed test assertions and django.utils.timezone.utc, among others. Target the version you are moving to at each step, not 5.2 from the start, because later fixers can produce code only a later Django understands. Pass it the file list (it does not recurse into directories) and run it before formatters such as Black or Ruff.
  • pyupgrade modernises Python syntax. Use the flag for the oldest Python you run in production, for example --py312-plus. Its current release itself needs Python 3.11 or newer.
  • makemigrations --check fails when a model change has no migration. Some django-upgrade fixers, including the index_together one, change models, and its documentation recommends a test for pending migrations.
python -m pip install django-upgrade pyupgrade

# Rewrite deprecated Django code, up to the version you are moving to
git ls-files -z -- '*.py' | xargs -0r django-upgrade --target-version 5.0

# Modernise syntax for the oldest Python you run in production
git ls-files -z -- '*.py' | xargs -0r pyupgrade --py312-plus

# Fail if any model change is missing a migration
python manage.py makemigrations --check

Database and deploy: rehearse, then cut over

Rehearse each step on a restored copy of production first. Then release it like anything risky: in a quiet window, with a tested way back.

  1. Restore a recent production backup to a separate database. This proves the backup works and gives you real data to test with.
  2. Upgrade the database server first if Django needs it. Do it on the copy, then ship it as its own change.
  3. Run the new migrations against the copy and time them. A migration that takes a second on a test database can take far longer, and hold locks, on a large production table.
  4. Test the real flows on a staging site pointed at the copy: sign-in, billing, the admin, file uploads, emails and scheduled jobs.
  5. Decide how far each step travels. Release 5.0 and 5.1 to production one at a time to keep each change small, or take each step to green on a branch and release 5.2 in one cutover. Either way, do not stay on 5.0 or 5.1.
  6. Cut over with a way back. Take a fresh backup just before the release, keep the previous build ready to redeploy, and know which migrations reverse cleanly. Django's upgrade guide also recommends clearing your cache, because cached pickled objects are not guaranteed to work across versions.
  7. Watch the first days closely in error tracking and slow-query logs, and keep the old environment until you are confident.

What drives the effort

The effort becomes predictable once you look at a few things in the codebase. The size of the app, on its own, is not one of them.

  • Test coverage. With good tests, most of the upgrade is mechanical. Without them, every change is checked by hand.
  • Third-party packages. One abandoned package can take more work than all of Django's own changes.
  • Custom code on Django internals. Releases remove undocumented APIs too; Django 5.0 removed BaseForm._html_output() and django.utils.datetime_safe. Apps that override internals take longer.
  • Templates tied to old markup. The form and admin markup changes reach every template and stylesheet that depends on them.
  • The database. A database below the new minimum adds an upgrade of its own, and large tables slow down migrations and rehearsals.

How we approach it at MicroPyramid

We start with an Upgrade Assessment, then run the upgrade as a fixed project that we finish and hand back to your team.

The Upgrade Assessment gives you a version, dependency and end-of-life audit of everything you run; an upgrade path with the test gaps and risks called out; and a cost and speed review of your cloud bill and slowest pages. The scope is agreed before any upgrade work starts, instead of being discovered halfway through.

The upgrade is then a fixed project: missing tests added, each Django step taken on its latest patch release, abandoned packages replaced, a rehearsal on a restored copy, and a cutover with a rollback plan. We hand the upgraded app back to your team with notes on what changed. To keep it on supported versions afterwards, our software maintenance runs month to month with 30 days' notice. More on our Django work: Django modernization.

Still on Django 4.2? Tell us what you run and we will show you what the path to 5.2 looks like for your app.

Frequently Asked Questions

Is Django 4.2 still supported?

No. Django 4.2 LTS lost security support on April 7, 2026, and 4.2.30 is its final release. The supported releases are 5.2 LTS (until April 2028), 6.0 (until April 2027) and 6.1 (until December 2027).

Can I jump straight from Django 4.2 to 5.2?

You can, but Django's upgrade guide recommends going through each feature release on its latest patch release, even between LTS releases. Stepping through 5.0 and 5.1 keeps each change small, so when a test fails you know which release caused it.

Which Python version should I use with Django 5.2?

Django 5.2 supports Python 3.10 to 3.14 (3.14 from 5.2.8), but 3.10 reached end of life on October 1, 2026. Move to 3.12 first, because every Django release from 4.2.8 to 5.2 supports it, then consider 3.13 or 3.14 once you are on 5.2 and your packages allow it.

Should we upgrade to 5.2 now or wait for Django 6.2 LTS?

Upgrade now. Django 4.2 already gets no security fixes, 6.2 LTS is not due until April 2027 (supported until April 2030), and the recommended path to 6.2 runs through 5.2 anyway, so none of the work is wasted. After 6.2, Django moves to yearly releases named after the year, starting with Django 2028 in January 2028, each with three years of support.

Do we need to upgrade our database as well?

Possibly. Django 5.2 needs at least PostgreSQL 14, MySQL 8.0.11, MariaDB 10.5 or SQLite 3.31.0. If you are below that, upgrade the database on a restored copy first and release it as its own change.

Can we stay on Django 5.0 or 5.1 for a while?

Not safely. Django 5.0 lost security support on April 2, 2025, and 5.1 on December 3, 2025, so use them only as steps on the way to 5.2.

What drives the effort of a Django upgrade?

Mostly test coverage, third-party packages that need updating or replacing, custom code that relies on Django internals, and the database version and size. An assessment looks at each of these first, so the scope is known before upgrade work starts.

Share this article
Related service Django Development Services

Start with a discovery call.

  1. 01 · TODAY Book a free 30-minute call Tell us what you run and where it hurts.
  2. 02 · WITHIN 24 HOURS We reply From the engineers you would work with.
  3. 03 · ON THE CALL Your first step A fixed-scope sprint or audit, not an open-ended retainer.
Book a Free Discovery Call
Email
hello@micropyramid.com
Phone
+91 99591 66266
Offices
Plano --:--Hyderabad --:--Sharjah --:--
You own
All code & IP, from day one

We reply within 24 hours