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 · 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

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.
• 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

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".

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.

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.

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.

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.

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@v0
  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.

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.

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 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.

FAQ

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.