django-upgrade-report

Which of your dependencies block a Django upgrade, and in which order to upgrade them.

Quick start · Statuses · Usage · CI · How it decides · FAQ · Ecosystem · Changelog

Before you touch Django, you need to know whether the 20 to 200 packages your project depends on are ready for the new version, which of them you can upgrade today, and which have to move together with Django. Finding that out by hand means reading every changelog.

django-upgrade-report reads your lockfile, asks PyPI what every Django-related package declares, and gives you the upgrade plan: blockers first, then the smallest safe step for each package, in the right order.

uvx django-upgrade-report

Contents

• Highlights
• Quick start
• What the statuses mean
• Usage
  • Exit codes
  • Choosing the target
  • Where versions come from
  • Which Python
  • Upgrading Python too
  • Several projects
  • Wagtail and django CMS
  • Commands to run
  • Packages not from PyPI
• In CI
  • GitHub Actions
  • Every week, with what changed
  • pre-commit
  • GitLab CI
  • Anywhere else
• How it decides
• FAQ
• Related projects
• Contributing
• License

Highlights

• Knows the order. Separates upgrades you can ship today, on your current Django, from the ones that have to land in the same change as the Django bump. It also tells you when a release first needs a newer patch of your Django, or a newer version of another package.
• Smallest step, not latest. For every package it names the oldest release that declares support for the target, so each change stays small and reviewable.
• Reads what you already have. uv.lock, poetry.lock, pdm.lock, Pipfile.lock, requirements*.txt, pyproject.toml or an installed environment, transitive dependencies included.
• Honest about uncertainty. A missing classifier means "check manually", not "blocked". An upper bound written before the target was released is not taken as a promise. Packages without a release in two years, or marked inactive, are flagged.
• Knows your Python. Finds your project's Python version, warns when the target Django needs a newer one, and evaluates environment markers for your project, not for the machine running the tool.
• Made for pipelines and for people. Markdown for pull request summaries, versioned JSON for scripts, a self-contained HTML report to attach to a ticket, and --fail-on to break the build.
• The whole ecosystem, every week. How ready the 300 most downloaded Django packages are for each Django version, and how fast they caught up after each release.
• Your code stays put. Only names and versions of packages that come from PyPI are sent to PyPI. Git, path and private-index packages are listed, never looked up. No account, no configuration.

Quick start

Run it in your project directory. You need Python 3.10 or newer, but not Django and not your project's virtualenv.

uvx django-upgrade-report                      # with uv
pipx run django-upgrade-report                 # with pipx
pip install django-upgrade-report              # or install it

By default it picks the next sensible step for your project: the newest LTS above the Django you run, or the newest release when no LTS is above it. A project on Django 4.2 gets a report for 5.2, a project on 5.2 one for 6.1. Pick another target with --target:

django-upgrade-report --target 6.1

To move through a long report instead of scrolling it, open it in the terminal with -i: the sections and packages on the left, the chosen package on the right with its notes, signs, command and links. / searches, f shows one status, space ticks a package off, e copies its command, o opens its changelog, t checks another target and w writes the report to a file. Ticks are kept in .django-upgrade-report/state.json in the project: add it to .gitignore, or commit it to share them. It needs the tui extra:

uvx --with textual django-upgrade-report -i
pip install 'django-upgrade-report[tui]'       # or install it with the extra

What the statuses mean

The notes on a row tell you more, for example "update Django 4.2 first" when a release needs a newer patch of your current Django, "upgrade django-crispy-forms first" when it needs a newer version of another package you pin, or "newer releases exclude Django 6.1".

An upgrade also says how big the step is, "crosses 2 major versions", counted by the releases in between, where each 0.x minor release counts as a major one. The rows of the Markdown and HTML reports link the package's changelog: the link its maintainers label as such, or its GitHub releases page. The text report shows the links with -v.

Some packages did a job Django now does itself, and no metadata says so. For a short list of them the row says what Django has instead, for example "built into Django 1.7: its own migrations, remove South" or "built into Django 3.1: models.JSONField" for django-jsonfield. An entry needs a source, the package's maintainers pointing to Django or Django's release notes; quiet packages, or opinions about a better third-party package, stay out. The list is in successors.py, and additions with a source are welcome.

Usage

django-upgrade-report [PROJECT ...] [options]

Responses are cached in ~/.cache/django-upgrade-report (or $XDG_CACHE_HOME/django-upgrade-report): a project's release list for 24 hours, the metadata of a single release for good, since it never changes. A new version of the tool may keep more of each answer; it then fetches them once more and ignores the old files, so delete the directory now and then to free the space.

Exit codes

So CI can tell "packages need attention" from "the tool could not run".

Choosing the target

The report warns when the target skips an LTS (upgrading one LTS at a time is easier), when your own Django requirement excludes the target, and when the target needs a newer Python than your project uses.

--via lts plans the whole way in steps, one report per LTS on the way, --via each one per feature version:

$ django-upgrade-report --target 5.2 --via lts
Django 3.2.25 → 4.2 → 5.2 (2 steps)

Step 1 of 2
Django 3.2.25 → 4.2
  ↑ django-filter  21.1 → 23.1  …

Step 2 of 2
Django 4.2.30 → 5.2
  ↑ django-filter  23.1 → 25.1  …

Each step starts where the one before ends: its upgrades done, Django on the newest patch of that release. A package blocked in one step says so in the later ones, since the plan stops there. --fail-on looks at every step. The JSON report of a path has "kind": "path" and one report per step; Markdown folds each step, and the HTML report shows them on one page under an overview, with one checklist for the whole way. It does not go with --baseline, --emit or --explain.

Where versions come from

The most precise source wins:

Requirement files follow -r includes and -c constraint files; constraints only pin packages that are listed elsewhere. pyproject.toml is read as PEP 621, dependency groups and Poetry. When a lockfile holds several versions of one package for different Pythons, as uv's forked resolutions do, the one for your project's Python is used.

Unpinned requirements are judged by the newest release they allow and marked as such. Use a lockfile for exact results. When Django itself is only given as a range with an upper bound, such as Django>=4.2,<5.0, the newest release it allows is assumed and a warning says so. Without an upper bound the report cannot tell what can be upgraded first. In both cases, --from sets the version you run.

Which Python

Environment markers such as python_version < "3.12" decide which requirements apply, so the tool needs your project's Python. It takes the first of:

1. the interpreter passed with --python,
2. .python-version,
3. requires-python in uv.lock,
4. requires-python in pyproject.toml,
5. the python dependency in Poetry's pyproject.toml,
6. python_version in Pipfile.lock.

A range counts as its lower bound. The report shows the Python it found and warns when the target Django needs a newer one, for example Django 6.1 needs Python >=3.12, your project uses 3.11 (from .python-version).

Markers are evaluated for CPython on Linux, where Django apps are deployed, never for the machine running the tool. Against the target, a package is judged on the newer of your project's Python and the oldest Python the target Django supports. Against your current Django, on your project's Python, or the oldest Python your current Django supports when none was found.

Upgrading Python too

Django 6.0 needs Python 3.12. When the target Django needs a newer Python than your project uses, the report starts with what your dependencies need on it, all of them, not only the Django-related ones:

Python 3.12 first (2)
  These dependencies need something before they run on Python 3.12.
  ↑ numpy            1.22.4 → 1.26.0  1.22.4 no wheel for Python 3.12, pip builds it from source
  ↑ psycopg2-binary  2.9.3 → 2.9.9    2.9.3 no wheel for Python 3.12, pip builds it from source
  3 more dependencies run on Python 3.12, all pure Python.
  1 says nothing about Python versions: pycrypto.
  Django 4.2.7 does not declare Python 3.12, 4.2.8 does: update Django 4.2 first.

For each installed release, in this order: a Requires-Python that excludes the Python means no; a Programming Language :: Python :: 3.12 classifier means yes; so does a wheel built for it. An abi3 wheel for an older Python, or a pure-Python wheel, runs too. Wheels only for other Pythons mean pip builds the package from source, which needs a compiler and often fails; without a source distribution it cannot be installed at all. Wheels count when they install on CPython under Linux on x86_64. A dependency that needs something gets the oldest newer release that runs on the Python, with a note when that release no longer runs on the Python you use today, so it goes together with the switch. It needs a project Python (see above); --python-target 3.13 checks any Python you name.

Several projects

For a monorepo or a folder of services, pass several projects, or let --recursive find them:

$ django-upgrade-report -r services --target 5.2
3 projects
  services/admin   Django 5.2 · health check  0 ready · 2 to upgrade · 0 to check · 0 blocked
  services/api     Django 4.2.7 → 5.2         30 ready · 5 to upgrade · 1 to check · 2 blocked
  services/worker  Django 4.2.7 → 5.2         12 ready · 3 to upgrade · 0 to check · 1 blocked

Blocking more than one project
  django-taggit  services/api, services/worker

Upgrades several projects share
  django-filter → 25.1  services/admin, services/api, services/worker

Each project's report follows, folded in Markdown; the HTML report links each project from the overview. Every project has its own target (auto unless you pass --target), and a package several projects use is looked up once. --recursive skips virtual environments, node_modules and hidden directories, and a directory inside a project, such as requirements/ or a package with its own pyproject.toml, belongs to that project unless it has a lockfile of its own. A project that cannot be checked is listed with the reason, the others are still reported, and the run exits with 2. --fail-on looks at every project. The JSON report has "kind": "multi", with projects, blocking and shared_upgrades. -i, --emit, --explain, --via, --baseline, --python and --scan-code work on one project. In the GitHub Action, path takes one project per line, and recursive: true finds them.

Wagtail and django CMS

--framework wagtail (or django-cms) plans the upgrade of that framework instead of Django's: --target, the sections, the commands and the bot configurations are about Wagtail, and only packages that depend on Wagtail or declare Framework :: Wagtail are checked. Wagtail's LTS releases come from its release schedule, so auto is the newest of them; django CMS has none, so auto is its newest release. The report also says whether the target runs on your Django ("Wagtail 7.0.9 requires Django>=4.2: your Django 4.2.16 is fine"), and when it does not, which Django to upgrade to first. For django CMS, plugins named djangocms-… count even when they declare neither django CMS nor its classifiers. The Python plan, --evidence and the list of what Django removed stay Django's and are left out. The GitHub Action takes framework.

django-upgrade-report --framework wagtail --target 7.0

Commands to run

--emit uv (or poetry, pdm, pipenv, pip, or auto to pick by the lockfile) prints the commands that carry out the plan instead of the report: the upgrades that go first, one command each, then Django with what needs it, in one command; blocked packages and ones to check are named at the end. For pip it says which requirement lines to change. With --format json they go into the commands field. See Upgrade commands.

Packages not from PyPI

Packages from git, a local path, a URL or a private index are listed as "Not from PyPI, not checked", with where they come from, and their names are never sent to PyPI. This covers git+https://..., -e and local path lines in requirement files, name @ url requirements, git, path and URL sources in lockfiles, --index-url and --no-index in requirement files, a private default index or no-index in uv, Poetry, PDM or Pipenv, and the PIP_INDEX_URL, UV_INDEX_URL, UV_DEFAULT_INDEX, PIP_NO_INDEX and UV_NO_INDEX environment variables (lockfiles keep the index they record). Credentials in those URLs are removed before anything is shown.

A fork or a local package can still be judged by what it declares itself, without anything being fetched: the installed metadata with --python, the pyproject.toml of a local directory, or the constraints poetry.lock and pdm.lock record. A fork someone pinned years ago with Django<4.1 shows up as blocked, with a note saying where it comes from. Such a package has no other releases to move to, so it is only ever ready, blocked or to check. Its own requirements count, too: a fork that pins django-filter<23 holds back that upgrade. Packages whose metadata cannot be read, or that have nothing to do with Django, stay under "Not from PyPI, not checked". The dependencies of a fork are checked like any other package when a lockfile or --python lists them.

To check packages from a private index, point --index-url at its PyPI JSON API. If the index only mirrors PyPI, pass --check-private-on-pypi instead. Packages the index does not know at all are listed as "Not on the package index".

In CI

GitHub Actions

The action writes the Markdown report to the job summary, exposes the counts as outputs, and can fail the job:

- uses: actions/checkout@v7
- uses: derblub/django-upgrade-report@v1
  id: django
  with:
    fail-on: blocked   # optional: blocked, upgrade or check
- run: echo "${{ steps.django.outputs.blocked }} blocked, ${{ steps.django.outputs.upgrade }} to upgrade"

The action brings its own Python, runs on Linux and Windows runners, and caches PyPI responses between runs. The summary and the outputs are written before fail-on fails the step.

Every week, with what changed

examples/weekly.yml runs the report every Monday and keeps it in the Actions cache for next week. Each summary then starts with what changed, such as a blocked package that has a release for the target now, and the step fails when something needs more attention than before. On the command line, the same is --baseline last.json, with --only-changes to print nothing in a quiet week.

pre-commit

- repo: https://github.com/derblub/django-upgrade-report
  rev: v1.1.0
  hooks:
    - id: django-upgrade-report

The hook runs when a lockfile, a requirements file or pyproject.toml changes, and fails the commit when a package blocks the next Django upgrade. It answers from the cache where it can (--prefer-cache), shows only what blocks (--quiet), and lets the commit through when the report cannot be made (--errors-as-warnings). It reads the project at the repository root and runs when one of its files changes. Add args: [--target, "6.1"] to check another target.

GitLab CI

django-upgrade-report:
  image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
  script:
    - uvx django-upgrade-report --format html --output upgrade-report.html
    - uvx django-upgrade-report --fail-on blocked
  artifacts:
    when: always
    paths: [upgrade-report.html]

Anywhere else

django-upgrade-report --format markdown >> "$GITHUB_STEP_SUMMARY"
django-upgrade-report --format json --output upgrade-report.json

The JSON report carries a schema_version: adding a field keeps it, renaming, removing or retyping one bumps it. The fields are documented in render/json.py.

How it decides

For every release the tool looks at two pieces of metadata that maintainers publish on PyPI: the Framework :: Django :: X.Y classifiers and the Django requirement. For a target version, in this order:

1. A requirement that excludes every release of the target means no. Each patch release counts, so Django==5.2.17 or Django>=5.2.3,<5.2.8 allow 5.2. Requirements that only apply to an optional extra are ignored. Lines with environment markers count when they apply to your Python (see above), and all lines that apply are combined.
2. A Framework :: Django :: 5.2 classifier means yes.
3. An upper bound that allows the target, such as Django>=4.2,<6.0 or an exact pin, means yes, but only when the release was uploaded on or after the day the target came out. A bound written before that is a guess, not a promise: Wagtail 6.3 allows Django<6.0 but came out before Django 5.2, and only Wagtail 6.3.4 added 5.2 support.
4. Everything else means not declared: classifiers that stop at an older version or start at a newer one, a major-only classifier such as Framework :: Django :: 5, a lower bound without an upper one, or no information at all. That is a question, not a blocker: classifiers often lag behind releases.

For a target that is not released yet, such as 6.2 today, only classifiers count, and the report says so. An upper bound like <7.0 says nothing about a version nobody could test.

Pre-releases never decide a status: you cannot pin an rc in production. When no stable release declares the target but the newest pre-release does, the row says so, for example "2.6.0.dev22 declares Django 6.1 (pre-release)". For a blocked package it also says when the newest pre-release no longer excludes the target. Only a pre-release newer than every stable release counts, judged by the same rules.

From these verdicts, per package:

• Ready when the version you use says yes.
• Upgrade when a newer release says yes. The report names the oldest one. It goes first when that release still runs on your current Django. A release that needs Django>=4.2.16 while you run 4.2.7 still goes first, with a note to update Django 4.2 first. It goes together with Django when the release excludes your whole Django series, declares only newer Django versions, or needs a newer version of another package you pin that has itself dropped your Django.
• Check manually when no release says yes, but yours or a newer one is not excluded.
• Blocked when your release and every newer one exclude the target.

A package to check can still show signs of support: its README on PyPI naming the target ("README of 2.1 mentions Django 5.2"), for the release the report names or else the newest. With --evidence, also its GitHub repository: a test matrix on the default branch that runs the target (tox, nox or a GitHub workflow: "main branch tests Django 6.0 (tox.ini)"), and a changelog section after your version that adds or tests it ("changelog of 1.14.5 mentions Django 5.1 support"). For blocked packages and ones to check without a sign, it also lists up to two issues or pull requests whose title names the target ("open PR: Add Django 5.2 support (#912)"; a merged one means the next release likely has it). Signs are notes, linked to where they come from, and never change a status or --fail-on. Packages to check without any sign come first, since that is where the work is.

A direct dependency that your code never names gets the note "not imported or configured in your code: remove it instead?": removing it is often less work than upgrading it. The code in the project directory is read locally, never imported and never sent: imports, dotted paths in strings (INSTALLED_APPS, MIDDLEWARE, ENGINE and the like), app lists, {% load %} in templates and manage.py commands in scripts. Anything unsure counts as used: servers and tools you run rather than import, a project with more than 20,000 files, and one without Python code give no note. The end of the report lists every direct dependency the code never names, Django-related or not, as "Possibly unused"; --explain says where the code uses a package. With --python, the module names come from the environment itself instead of a table. --no-scan-code turns it off.

After the packages, the report lists what Django removed on the way to the target, from the "Features removed" sections of its release notes, and which of it your code still uses: "The model's Meta.index_together option is removed shop/models.py:11 · django-upgrade fixes this". Only the used ones are shown, the rest as a link to the release notes; -v shows all. A removal counts as used only when the code names the very thing that is gone: an import, a setting, a Meta option, a template filter, a method. Rewriting the code is the job of django-upgrade.

A package counts as Django-related when it depends on Django or has a Framework :: Django classifier. Packages that only depend on Wagtail or django CMS are included too, with a note to check them against that framework. Everything else is skipped. With --framework wagtail the same rules apply to Wagtail, with one difference: Wagtail's classifiers name major versions only (Framework :: Wagtail :: 6), so such a classifier means yes for 6.3 when the release came out after 6.3 did, and not declared before.

FAQ

$ django-upgrade-report --emit dependabot
    groups:
      django-5-2:
        patterns:
          - "django"
          - "django-with"
    ignore:
      # Hold Django at 4.2 until the 'upgrade first' list is done, then remove this.
      - dependency-name: "django"
        versions: [">=5.0"]

Related projects

Contributing

Bug reports with a real lockfile are the most useful contribution. See CONTRIBUTING.md for the development setup, and the Code of Conduct. Security issues go through SECURITY.md.

License

MIT © Daniel Kurdoghlian, Pushing Pixels

Built and maintained by Daniel Kurdoghlian at Pushing Pixels in Vienna.
Planning a larger upgrade? I do fixed-price Django upgrade audits.