A Django Upgrade Guide for Major and Minor Releases

The Django project has major updates every eight months and minor updates as needed. It's a good idea to keep your project up to date with the latest version or at least a supported version. This keeps your application secure and allows you to use new features like ASGI support, built-in cross-db JSON field, upcoming functional indexes, and more.

With the upcoming Django 3.2 release in mind, this post goes through the general process for updating a Django project.

How to Upgrade to Minor Releases of Django

Patch releases are made available as needed.

These minor releases fix bugs and security issues in the major version. Always upgrade your projects to the latest patch of the major version you are running. It is easy and there is no reason not to do this.

Per the Django documentation:

These releases will be 100% compatible with the associated feature release, unless this is impossible for security reasons or to prevent data loss. So the answer to "should I upgrade to the latest patch release?” will always be "yes."

Here's how to upgrade using the latest minor patch

1. Read the release notes and pay attention to anything that might affect your project. Since the minor releases are “100% compatible with the associated feature release” there should be nothing you need to change in your project, with the exception of the next step below.
2. Change Django version in requirements file. For example if you are running Django==3.1.6 and the 3.1.7 patch comes out you will update your requirements file to Django==3.1.7
3. Install the updated requirements and test your project.
4. That's it. You've completed the upgrade.

How to Upgrade to Major Releases of Django

Feature releases are made available every 8 months.

Version 3.2 comes out in April of 2021 and is going to be a long term support (LTS) release.

Every .2 release will be a LTS release starting with 2.2. Prior to 2.2 there LTS releases did not end in .2 (1.11, 1.8, etc).

It is a good idea to keep up with the latest Django version even if it is not a LTS release. You get the latest security enhancements, features, and performance improvements. You also reduce technical debt of upgrading down the road when you are multiple versions behind.

Here's how to upgrade using the latest major release

1. First, add a source control system such as Git to your application if it isn’t already. This will allow you to maintain various versions of your application such as the old version and your work-in-progress upgraded project. If you need help, find an authorized GitLab partner to make sure you're doing it right.
2. Dockerize your application if it isn’t already. This isn’t necessary but it is extremely helpful when you are upgrading from an ancient version of Django (or Python 2, database, cache, etc). (If you are still on Django 1.1 you are not alone - I recently upgraded one of those.).
3. Test the project and add tests where they are lacking. Automated software tests are a lifesaver in keeping software up to date.

• Run tests with python -Wall manage.py test and deal with any deprecation warnings

1. Read the release notes for the major Django version that comes after the version you are currently running. Make any changes to your project. If any third party packages you are using are not compatible with the new major Django version, you will need to also read those release notes and update your project accordingly.
2. Change your requirements file to use the new major Django version and any dependencies that need to be updated. Install the updated requirements.
3. Run Django checks with python -Wall manage.py check

• Fix any issues and deal with any deprecation warnings

1. Run tests with python -Wall manage.py test

• Fix any issues and deal with any deprecation warnings

1. Repeat steps 4 through 10 until you get to the latest version of Django
2. Upgrade all dependencies to supported versions. Basically, repeat steps 4 through 10 but with the third party packages instead of with Django.

How Do I Upgrade If I'm on Python 2?

If you are still on Python 2, it's time to jump ship and get on board with Python 3.

The steps to update are the same but first, upgrade to Django 1.11 while staying on Python 2, then switch to Python 3, test, and continue the Django upgrade to the latest version. Django 1.11 is the last Django version to support Python 2 and it is also the beginning of where Django upgrades become very stable.

What if I’m using a Django version under 1.7 (Where migrations were added)?

As with everything this can vary on a project-by-project basis but the simple version is upgrade to Django 1.7, delete any south migrations, generate new initial migrations that match the existing database schema, and then run them. If you are running the new migrations for the first time on Django 1.8 or greater then use the --fake-initial flag.

Once the migrations are finished, continue upgrading Django to the latest version.

What if my database is no longer supported by Django?

First things first, backup your database(s). If the project is small enough then the simplest solution might be to use python manage.py dumpdata and python manage.py loaddata to copy the data from the old database version into a newer database.

For larger projects refer to database specific guides for tools such a pg_upgrade or mysql_upgrade.

Summary

Upgrading software can be intimidating but there is no better time to do it than now since it only gets more difficult and insecure down the road. Tools such as source control and Docker help reduce environment differences and lead to a better development/deployment experience. Finally, automated testing is a massive help in preventing errors during regular development and software upgrades.

This post originally appeared on our devops consulting blog.