Upgrading Django: Tips You Don’t Get From Docs

Keeping Django upgraded is essential. Failing to keep your site up-to-date can result in serious security issues and major headaches — not to mention extra hours — for the developer.

The Django Foundation recommends staying with the most up-to-date version rather than relying on infrequent, long-term support (LTS) versions. In addition, there are many other circumstances that make upgrading Django a high priority for developers.

Whether it be a security problem that has been fixed with a new patch, or a new feature that requires an upgrade, I’ve seen it all. Here are some battle-scarred tips you should know to make your Django upgrade as smooth as possible.

What to know about upgrading different versions

Upgrading is an iterative process of examining dependencies and testing. If you have the task of upgrading from a very old version, you will need to go through this several times, as it is not advisable (and may not even be possible) to do the upgrade in one jump. See my colleague Roché’s blog, “How to Leapfrog a Massive Django/Python Upgrade Successfully,” for more on that.

However, be aware that the number of iterations may not be as many as it seems, since the Django version numbering scheme as of 2.0 only involves three minor revisions (0, 1, and 2). The x.2 version of each series (2.2 and 3.2, so far) is the LTS version for that series, not the x.0 version.

If your existing version is:

• Before 1.7: Consider re-architecting. These versions are so far behind (almost 10 years as of this writing) that it’s likely you will spend major amounts of time rewriting anyway.
• 1.7 to 1.11: You will likely need to upgrade Python 2 to Python 3 as well, which is a related but separate issue. 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. With this upgrade, you’ll probably need to spend a fair bit of time evaluating existing code to update to new techniques. Additionally, you might have some rewriting and research to do if it depends on old libraries that are no longer maintained or incompatible with newer versions.
• 2.0 to 2.2: The 2.0 version is the biggest single jump and most invasive of the upgrades. Since 2.0 and up requires Python 3, you will have fewer headaches to deal with. Specifically, you will have already upgraded from Python 2 during the 1.x series upgrades (remember to check which Python versions are supported by each Django version), so you will mostly need to deal with specific changes rather than entire broken subsystems. The note about old libraries still applies, however. You will likely have multiple opportunities for enhancement through new features.
• 3.0 to 3.2: With these versions, you should be sitting pretty well, and you might not have that much to do. Still, look for opportunities for performance improvement and code simplification. Also, make sure your supporting libraries are all fully updated.

Examine release notes between updates

During the iterative upgrade process, for each version, you’ll want to read the release notes so that you can answer the following questions:

• Is there functionality that is being removed in the new version that the existing application code relies on?
• Have there been changes in the new version that impact the existing code? Read these very carefully, as some changes may be very subtle in the way they might produce problems. Be prepared to search for upgraded versions of any additional packages installed, besides Django itself, as well as their supporting native libraries, if any.
• Are there new features that could be used to fix problems or enhance performance?

Pro-tip: I recommend reading through the release notes for all non-patch releases at once, rather than incrementally. This will give you an overall sense of what newer features may be available — and what older techniques may need to be modified.

Plan and execute testing

When doing large upgrades, it’s very important to have a good suite of tests that will catch any regressions that show up in upgraded versions. The tests should cover the three major sections of Django:

• models;
• views; and
• templates.

The models are the most important, and consequently, the model tests should always pass in order to call an upgrade successful. Often, the second two sections may be viewed as less critical, and test failures in their suites may be tolerable until reaching the final target version of Django.

Pro-tip: I highly recommend Brian Okken’s book, Python Testing with pytest, for more on testing.

When a site is being moved from using Django views and templates to a more frontend-heavy style using a single-page browser app and a REST, GraphQL, or WebSocket API, the tests of the old views and templates may not matter.

Once you have the codebase at the current version of Django (which is 4.0.3 as of this writing), plan for future upgrades of Django and supporting libraries as a part of normal development. This will ensure that your site stays secure and gains all the benefits of new Django versions. Even the tip of the main development branch is useful to try in development and testing, as the Django core developers work very hard to keep it in full working order.

Read more Django blogs from Six Feet Up developers, and sign up for our newsletter — ACCELERATE — for monthly tech tips.