How to upgrade Django - a step-by-step guide

When we work on large-scale projects, they usually take years to develop. In this situation, it is no wonder that the technologies used in the beginning have become obsolete, and there comes a time when they need to be updated with more recent ones.


Why do we update the software? 

First, new technologies frequently allow us to achieve the same functionality with less code because they offer additional implementation options. Also, new versions of technologies provide superior protection against malicious activity as, in most cases, the hackers have already discovered old systems' security flaws and ways to overcome them. The most recent versions also include new features that we can use. 

These are the main reasons we want a software to be updated frequently.


The goal 

Let's say the most recent long-term support (LTS) version of Django is the selected version we want to upgrade. If you have more than one version between the current and desired, it is not a good idea to switch directly to it. Instead, make it in steps for each LTS version and release it separately. An efficient upgrade process helps make the upgrade smoother, encouraging it to happen at each release point. 


Here are the currently supported versions of Django:  

Source: Django website


In this blog post, I look at the process we followed for our bespoke applications, refined by the experience of each previous upgrade.


The process in steps


Planning and Preparation

Planning comes first. Choose the suitable libraries after selecting the Django version. Keep in mind that a project may not be able to run with a newer version of Django and its older libraries because many of them won't be compatible.

The preparation comes next. We create an excel table with all the libraries currently used in the project.

The following step is checking that this newer version doesn't require a more recent Python. Versions of Django are matched with specific ranges of Python versions that were available when that version was developed, so Python upgrading is an iterative process.

The next step in the planning process is to find the release notes - read every release note of the Django version, which is greater than the current one. Understand the changes of version release notes and every modification that must be made to the code in order for the project to use the newer version. Read these carefully, as some changes may be very subtle in how they produce problems. Then, we're prepared to take action.



Beginning with the Django release notes and all those changes is a good place to start. After that, changing a few imports is half the job. For example: 

  • When upgrading from 1.11 to version 2.2 I replaced the "from django.core.urlresolvers import reverse" with "from django.urls import reverse"
  • -from rest_framework.filters import DjangoFilterBackend

+from django_filters.rest_framework import DjangoFilterBackend

  • Deprecate the Router.register base_name argument in favor of basename

There might be some small changes to the code like:

  • Add ForeignKey on_delete method
  • Replace @detail_route uses with @action(detail=True, )
  • Replace @list_route uses with @action(detail=False, )
  • add default on nested serializer field
  • Fix many reverse urls calls

Continue by updating the Django Rest Framework version and all of the libraries from Excel, noting the version you receive.

Of course, some might not be able to be upgraded using the previous version of Django so you can save those for last. For example, one of our updates had an issue with the package that enables us to save data in JSON format. The more recent version of Django supports that specific field. So I had to remove the old library and migrate the data. Converting the djoser library was the hard part, but nothing impossible. Finally, when all libraries are upgraded it is time to raise the actual Django.


Final checks and testing

The "python check" command comes in handy, which returns the potential issues with the fixing code. Please pay attention not only to errors but also to warnings. After that, start debugging and run the unit tests. Finally, when all possible fixes have been made, the work has been completed in half; the remaining tasks include rising the Django version, fixing all unit tests, and using the "python check" command to detect issues.

When everything is prepared, it's time to launch the front end and thoroughly examine each page and each button to ensure they all work as intended. This is even before the QA team receives it to test.

And be sure to review your checklist to see if there are any items you haven't gotten to yet.


In conclusion 

Upgrading software can be frightening, but there is no better time to do it than now since it only gets more complicated and insecure down the road. Here's what our checklist includes:

  1. Choose the proper Django version. LTS preferred.
  2. Read the Release Notes, and make a checklist.
  3. Review and make a list with third-party package compatibility.
  4. Update the DRF and all libraries.
  5. Get the tests passed.
  6. Manually test critical components.
  7. Clear your checklist.
  8. Deploy a test environment and let the QA team approve it.
  9. Deploy staging for final checks.
  10. Deploy production and enjoy the well-done job.


If you need help keeping your projects up to date, contact us. We would be happy to learn more and to help.


– Author: Pavel Penchev, Python Developer


By clicking the Accept button, you are giving your consent to the use of cookies when accessing this website and utilizing our services. To learn more about how cookies are used and managed, please refer to our

Cookie Statement & Privacy Policy