Command Line Reference

Command-line reference

django-upgrade-report [PROJECT] [options]

Every option, as django-upgrade-report --help describes it. The pages Getting started, How it decides and Continuous integration show them at work.

Option	Value	Default	What it does
PROJECTS	PROJECT		Project directory with a lockfile, requirements*.txt or pyproject.toml (default: current directory); several make one report with an overview.
--recursive, -r			Find the projects under PROJECT (a monorepo, a folder of services): every directory with a lockfile, requirement files or pyproject.toml dependencies.
-t, --target	TARGET	auto	Django version to upgrade to: 'auto' (default: the newest LTS above your Django, or the newest release when no LTS is above it), 'lts', 'latest' or e.g. '5.2'.
--from	VERSION		The Django version you run today, e.g. 4.2 or 4.2.16, when your requirements only give a range.
--framework	django wagtail django-cms	django	What to plan the upgrade of: django (default), or wagtail or django-cms, whose packages are then checked against --target and --from of that framework.
--via	lts each		Go to the target in steps, one report each: through every LTS on the way, or through each feature version.
--python	PATH		Read exact versions from the packages installed for this interpreter, e.g. .venv/bin/python.
-f, --format	text markdown json html	text	Output format (default: text).
-o, --output	OUTPUT		Write the report to a file.
--emit	auto uv poetry pdm pip pipenv renovate dependabot		Print the commands that carry out the plan instead of the report, for this tool; 'auto' picks it by the lockfile. With --format json: the commands field. 'renovate' and 'dependabot' print a configuration that makes the bot follow the plan.
--static			With --format html: a page without scripts, no search, filters or checklist counter, for places that block scripts in attachments.
--fail-on	blocked check upgrade		Exit with status 1 when a package is blocked, needs an upgrade or needs a check (errors exit with status 2).
--fail-on-python	blocked check upgrade		Like --fail-on, for the dependencies on the newer Python (see --python-target).
-v, --verbose			List ready packages too.
--baseline	REPORT.json		An earlier --format json report: start with what changed since.
--only-changes			With --baseline: show only what changed, and nothing when nothing did.
--fail-on-change	any worse		With --baseline: exit with status 1 when anything changed, or when something needs more attention than before.
--python-target	VERSION	auto	Check every dependency on this Python too, e.g. 3.12: 'auto' (default) when the target Django needs a newer Python than your project uses, 'none' never.
--explain	PACKAGE		Show step by step how the verdict on PACKAGE came about, instead of the report; can be given more than once.
--evidence			For packages to check, look for signs of support in their GitHub repository: the test matrix of the default branch. Sends the repository names to GitHub.
--no-scan-code			Do not read your code to find dependencies it never uses (it is read locally and never sent anywhere).
--scan-code	DIR		Read the code in DIR for dependencies it never uses; the default is the project directory, and nothing when PROJECT is a file.
-i, --interactive			Move through the report in the terminal instead of printing it; needs the tui extra: pip install 'django-upgrade-report[tui]'.
-q, --quiet			Text output only: the headline, warnings, blocked packages and the counts.
--index-url	INDEX_URL		PyPI JSON API base URL (default: https://pypi.org/pypi). Packages your project installs from another index are looked up only when you pass this.
--check-private-on-pypi			Look up packages your project installs from another index on PyPI, too: for an index that mirrors PyPI (Artifactory, Nexus, devpi). Their names are sent to PyPI.
--no-cache			Do not cache PyPI responses.
--offline			Answer from the cache only, however old, and never ask the package index.
--prefer-cache			Answer from the cache, however old, and ask the index only for what is missing.
--no-input			Never ask in the terminal what the project leaves out, such as your Django version when it is not pinned.
--errors-as-warnings			Exit with status 0 instead of 2 when the report cannot be made, e.g. offline: for hooks that must not block a commit.
--version			Show program's version number and exit.

Exit status

Status	Meaning
0	The report was written, and nothing matched --fail-on, --fail-on-python or --fail-on-change.
1	Something matched one of them.
2	The report could not be made: no dependencies found, an unreadable file, an unknown target, the index could not be reached, or with --fail-on a report that is incomplete. With --errors-as-warnings these exit with 0 and print a warning.