Pay particular attention to backwards incompatible changes to get a clear idea
of what will be needed for a successful upgrade.

If you’re upgrading through more than one feature version (e.g. 2.0 to 2.2),
it’s usually easier to upgrade through each feature release incrementally
(2.0 to 2.1 to 2.2) rather than to make all the changes for each feature
release at once. For each feature release, use the latest patch release (e.g.
for 2.1, use 2.1.15).

The same incremental upgrade approach is recommended when upgrading from one
LTS to the next.

In most cases it will be necessary to upgrade to the latest version of your
Django-related dependencies as well. If the Django version was recently
released or if some of your dependencies are not well-maintained, some of your
dependencies may not yet support the new Django version. In these cases you may
have to wait until new versions of your dependencies are released.

Before upgrading, it’s a good idea to resolve any deprecation warnings raised
by your project while using your current version of Django. Fixing these
warnings before upgrading ensures that you’re informed about areas of the code
that need altering.

In Python, deprecation warnings are silenced by default. You must turn them on
using the -Wa Python command line option or the PYTHONWARNINGS
environment variable. For example, to show warnings while running tests:

$ python -Wa manage.py test

If you’re not using the Django test runner, you may need to also ensure that
any console output is not captured which would hide deprecation warnings. For
example, if you use pytest:

$PYTHONWARNINGS=always pytest tests --capture=no

Resolve any deprecation warnings with your current version of Django before
continuing the upgrade process.

Third party applications might use deprecated APIs in order to support multiple
versions of Django, so deprecation warnings in packages you’ve installed don’t
necessarily indicate a problem. If a package doesn’t support the latest version
of Django, consider raising an issue or sending a pull request for it.

When the new environment is set up, run the full test suite for your application. Again, it’s useful to turn
on deprecation warnings on so they’re shown in the test output (you can also
use the flag if you test your app manually using manage.pyrunserver):

$ python -Wa manage.py test

After you have run the tests, fix any failures. While you have the release
notes fresh in your mind, it may also be a good time to take advantage of new
features in Django by refactoring your code to eliminate any deprecation
warnings.

When you are sufficiently confident your app works with the new version of
Django, you’re ready to go ahead and deploy
your upgraded Django project.

If you are using caching provided by Django, you should consider clearing your
cache after upgrading. Otherwise you may run into problems, for example, if you
are caching pickled objects as these objects are not guaranteed to be
pickle-compatible across Django versions. A past instance of incompatibility
was caching pickled HttpResponse objects, either
directly or indirectly via the cache_page()
decorator.