Introducing django-upgrade, a tool for upgrading your Django projects

Giddy-up, we’re going to the future!

Update (2021-01-07): My new book Boost Your Django DX covers django-upgrade and many other code quality tools that can improve your code.

Django deprecates a small list of features with every feature release, requiring us to update our projects, which can be monotonous. Today I’m announcing a new tool I’ve created, django-upgrade, that automates some of this drudgery for us all.

The Story

For a while I’ve enjoyed using pyupgrade, which upgrades Python syntax to the latest and greatest. pyupgrade is both fast and accurate, what you’d hope for in such a tool. The idea is to run it continuously, via pre-commit or similar, so that any new usage of old syntax you add gets automatically upgraded.

Last year, after a django-developers discussion, Bruno Alla created a similar tool for upgrading Django projects called django-codemod. django-codemod works well, and I’ve enjoyed running it on a few projects, saving me hours of boring find-and-replace. The only downside is that it’s relatively slow, taking up to several minutes on a medium sized project. This makes it okay for one-off runs, but it’s not suitable for running continuously (except on CI).

django-codemod’s slowness is due to the underlying library, LibCST, which implements its parser in Python. In contrast, pyupgrade is fast because it uses Python’s own C-based parser. LibCST also comes with compatibility concerns - it still doesn’t support Python 3.9, even though 3.10 is around the corner.

I have tried my hand at combining the best of pyupgrade and django-codemod into a new tool: django-upgrade. It’s available today on PyPI, although it doesn’t cover every recent deprecation, and it has a couple known bugs.

I started working on django-upgrade a few weeks ago without announcing it. Since then some people spotted it on GitHub and have chimed in, including Bruno. We’re working on getting django-upgrade to cover all the same fixes as django-codemod.


django-upgrade is a CLI that upgrades Python files in place. For example, imagine we had this model definition:

from django.db.models import Model, NullBooleanField

class Book(Model):
    valuable = NullBooleanField("Valuable")

Django deprecated NullBooleanField in version 3.1, in favour of BooleanField with null=True.

We can run django-upgrade on the file like so:

$ django-upgrade

After this, our field now uses BooleanField:

from django.db.models import Model, BooleanField

class Book(Model):
    valuable = BooleanField("Valuable", null=True)

django-upgrade runs fixers for many such cases, all documented in its README.

With pre-commit

django-upgrade can run every time you run git commit via pre-commit. The art here is to have it run before your general formatting tools, such as Black and isort. This allows django-upgrade to make its changes without worrying about matching your code style.

For example, here’s my current config on one project using django-upgrade (Python tools only):

  - repo:
    rev: v2.26.0
      - id: pyupgrade
        args: [--py39-plus]
  - repo:
    rev: 1.2.0
      - id: django-upgrade
        args: [--target-version, "3.2"]
  - repo:
    rev: 21.8b0
      - id: black
  - repo:
    rev: 5.9.3
      - id: isort
  - repo:
    rev: 3.9.2
      - id: flake8


Try out django-upgrade today. Bug reports are very welcome so we can ensure it only makes accurate replacements.



Learn more about pre-commit, particularly for Python projects, in my DX book.

Subscribe via RSS, Twitter, Mastodon, or email:

One summary email a week, no spam, I pinky promise.

Related posts:

Tags: ,