django-upgrade

Warnings

• gotcha django-upgrade makes changes to your code in-place. It's crucial to run it on a clean Git branch and review changes carefully. Always run your test suite after applying `django-upgrade` to catch any regressions.
  Fix: Commit pending changes, run `django-upgrade`, then meticulously review `git diff` and run your full test suite. Consider integrating it with `pre-commit` to catch new deprecations early.
• gotcha Some fixers (e.g., for `index_together` or `NullBooleanField`) make changes that necessitate new database migrations. After running `django-upgrade`, you may need to run `python manage.py makemigrations` and then `python manage.py migrate` to apply these schema changes.
• breaking django-upgrade requires Python 3.10 or newer. When upgrading to recent Django versions (e.g., Django 5.2), ensure your Python environment meets the minimum requirements, as older Python versions are no longer supported.
  Fix: Upgrade your Python environment to 3.10 or later before attempting to upgrade Django or use `django-upgrade` for newer Django versions.
• gotcha django-upgrade focuses on upgrading code to avoid deprecations, not on code style. It's recommended to run `django-upgrade` *before* code formatters like Black or Ruff to avoid conflicts or reformatting changes made by `django-upgrade`.
  Fix: Order your tooling: run `django-upgrade` first, then formatters like Black/Ruff.
• gotcha While `django-upgrade` automates many code changes, it does not replace the need to read Django's official release notes, especially for major version upgrades. Manual adjustments for breaking API changes, configuration updates, or third-party package incompatibilities will still be necessary.
  Fix: Always consult Django's release notes for each target version you are upgrading through, focusing on 'Backwards incompatible changes' and 'Deprecations'.
• breaking When targeting Django 5.2, ensure your database backend is also compatible. Specifically, PostgreSQL 13 support is dropped (requiring 14+), and MySQL requires version 8.0+.
  Fix: Upgrade your database server (e.g., PostgreSQL to 14+, MySQL to 8.0+) before or during your Django 5.2 upgrade process.

Install

• pip install django-upgrade Install latest version

Quickstart

django-upgrade is primarily a command-line tool. You typically run it against your project's Python files, optionally specifying a target Django version. It modifies files in-place by default.

# To apply fixers for Django 4.2 to all Python files in the current directory:
django-upgrade . --target-version 4.2

# Or, to process a specific file and print changes to stdout (without modifying in-place):
# django-upgrade myfile.py -