Django upgrade checklist: 12 steps that keep you live

That is the whole method. The rest of this Django upgrade checklist is the detail: which version to land on in late 2026, what to check before you touch the code, the commands that do the dull work for you, and how to ship each step without taking the site down. It works whether you are on Django 2.2, 3.2 or 4.2, and it is the same order we follow on client upgrades at Webbyfox.

If you are coming specifically from 3.2, our step-by-step plan for Django 3.2 to 5.2 covers the settings changes that usually bite on that route. This post is the general checklist that sits above it.

Which Django version should you upgrade to?

Upgrade to a version that still gets security fixes, and give yourself as long as possible before you have to do this again. As of 14 November 2026, Django's download page lists three supported release series:

The Python column comes from Django's installation FAQ. Django 4.2 and everything older are no longer on the supported list, so if you run any of them you are not getting security patches.

For most teams on an old version the answer is 5.2 LTS. It runs on Python 3.10, so you can often upgrade Django without changing Python in the same project, and it is covered until April 2028. Choose 6.1 only if you are already on Python 3.12 or later and happy to upgrade again before December 2027.

Two dates are worth putting in the diary. The download page schedules Django 6.2, the next long-term support release, for April 2027, with security fixes until April 2030. After that the numbering changes: Django's release process says that from Django 2028 there will be one feature release a year, named after the year, and every release will get three years of security fixes. There will be no separate long-term support versions. Small, regular upgrades will matter more than they do now.

Before you change any code

1. Write down where you are and where you are going

Note the exact Django and Python versions in production, not the ones in a README. Then list every feature release between them. Going from 4.2 to 5.2 means passing through 5.0 and 5.1. That list is your plan: one step per release.

2. Check the Python version first

Each Django release supports a fixed range of Python versions (see the table above). If your server runs a Python your target Django does not support, upgrade Python as its own step, on the Django you already have, and ship that before you start on Django. Changing both at once makes every failure harder to trace.

3. Audit your dependencies

Django's own upgrade guide says that in most cases you will need the latest version of your Django-related packages too, and that some may not support the new release yet. Go through your requirements and, for each Django package, find the first version that supports your target. Packages that are abandoned are the real risk. Find them now, because replacing one can take longer than the upgrade itself.

4. Put tests around the code that would hurt most

You do not need full coverage before you start. You need tests on the paths where a silent change would cost money or trust: payments, permissions, data imports, anything that sends email. We write those first on every upgrade. If your suite is thin, how we test Django applications covers the approach.

How to upgrade Django, one release at a time

5. Move one feature release per step

The Django guide recommends going through each feature release in turn rather than jumping straight to the target, and using the latest patch release of each. This matters because of how deprecation works: a feature is deprecated in one release, keeps working with a warning in the next, and is removed after that. Step through each release and the warnings tell you what to fix before the code breaks. Jump straight to the target and those warnings become errors all at once.

6. Read the release notes for that step

For each release, read the "Backwards incompatible changes" and "Features removed" sections of its release notes before installing it. Make a short list of anything that touches your code: settings, model options, template tags, database backends.

7. Turn deprecation warnings on and clear them

Python hides deprecation warnings by default. Run your tests with them switched on, on the version you are leaving, and fix them before you install the next one:

# Django's test runner
python -Wa manage.py test

# or, if you use pytest
PYTHONWARNINGS=always pytest tests --capture=no

Warnings that come from third-party packages are not necessarily your problem, but write them down: they tell you which packages need upgrading first.

8. Let a tool make the mechanical changes

Much of an upgrade is mechanical: swapping old code patterns for their newer equivalents. django-upgrade, written by Adam Johnson, rewrites that code for you. Give it the version you are moving to. It does not search directories itself, so pass it your files:

python -m pip install django-upgrade
git ls-files -z -- '*.py' | xargs -0r django-upgrade --target-version 5.2

Review the diff like any other change and commit it on its own, so the rest of the upgrade stays easy to read. To stop old patterns coming back, the tool's installation docs show how to run it as a pre-commit hook with the same --target-version.

9. Install in a clean environment and run everything

For a major upgrade the Django guide suggests building a new virtual environment with all your dependencies, rather than upgrading in place. Pin the exact patch release, install, then run the full test suite with warnings on again. Also run makemigrations --check to confirm the step has not left a migration you did not expect. Better to find it here than in production.

Shipping each step safely

10. Check production settings before you deploy

Deploy to a staging copy of production first, with real-shaped data. Run manage.py check --deploy against your production settings file. Django's deployment checklist explains what each warning means. Run it again on every step, not only the first.

11. Clear the cache when you go live

The upgrade guide warns that cached objects are not guaranteed to load in a different Django version. If you use Django's cache framework, plan to clear the cache as part of the release, and expect a short period of slower pages while it fills again.

12. Ship it, watch it, then start the next step

Each step goes to production on its own, and the site stays live throughout. Watch errors and response times for a few days before you start on the next release. If something does go wrong, you are rolling back one release, not three, and you know which release notes to read.

When to bring in help

Plenty of teams can follow this list themselves. It is harder when the original developers have left, the tests are thin, or a key package has been abandoned. That is the work our Django upgrade and rescue service is for: we upgrade the application you already have, one release at a time, each step shipped to production.

If you are not sure how big your upgrade is, start with a two-week discovery sprint. You get an audit of the codebase, a risk report and a firm plan before any upgrade work begins.

Questions