Upgrading Django to a newer version

While it can be a complex process at times, upgrading to the latest Djangoversion has several benefits:

  • New features and improvements are added.
  • Bugs are fixed.
  • Older version of Django will eventually no longer receive security updates.(see Supported versions).
  • Upgrading as each new Django release is available makes future upgrades lesspainful by keeping your code base up to date.Here are some things to consider to help make your upgrade process as smooth aspossible.

Required Reading

If it’s your first time doing an upgrade, it is useful to read the guideon the different release processes.

Afterwards, you should familiarize yourself with the changes that were made inthe new Django version(s):

  • Read the release notes for each ‘final’ release fromthe one after your current Django version, up to and including the version towhich you plan to upgrade.
  • Look at the deprecation timeline for therelevant versions.Pay particular attention to backwards incompatible changes to get a clear ideaof what will be needed for a successful upgrade.

If you’re upgrading through more than one feature version (e.g. A.B to A.B+2),it’s usually easier to upgrade through each feature release incrementally(A.B to A.B+1 to A.B+2) rather than to make all the changes for each featurerelease at once. For each feature release, use the latest patch release (A.B.C).

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

Dependencies

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

Resolving deprecation warnings

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

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

  1. $ python -Wa manage.py test
  1. ...\> py -Wa manage.py test

If you’re not using the Django test runner, you may need to also ensure thatany console output is not captured which would hide deprecation warnings. Forexample, if you use py.test:

  1. $ PYTHONWARNINGS=always py.test tests --capture=no

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

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

Installation

Once you’re ready, it is time to install the new Django version. If you are using virtualenv and it is a major upgrade, youmight want to set up a new environment with all the dependencies first.

If you installed Django with pip, you can use the —upgrade or -U flag:

  1. $ python -m pip install -U Django
  1. ...\> py -m pip install -U Django

Testing

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

  1. $ python -Wa manage.py test
  1. ...\> py -Wa manage.py test

After you have run the tests, fix any failures. While you have the releasenotes fresh in your mind, it may also be a good time to take advantage of newfeatures in Django by refactoring your code to eliminate any deprecationwarnings.

Deployment

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

If you are using caching provided by Django, you should consider clearing yourcache after upgrading. Otherwise you may run into problems, for example, if youare caching pickled objects as these objects are not guaranteed to bepickle-compatible across Django versions. A past instance of incompatibilitywas caching pickled HttpResponse objects, eitherdirectly or indirectly via the cache_page()decorator.