django-upgrade

library1.30.0pypypiunverified

django-upgrade is a tool that automatically upgrades your Django project code. It changes code to avoid deprecation warnings and migrates some patterns to newer Django idioms, easing the upgrade process and helping ensure your code uses the latest features. It is currently at version 1.30.0 and is actively maintained.

testing devops

pip install django-upgrade

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-UPGRADE

django-upgrade

testingpythonv1.30.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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 -

django-upgrade --version

Debug

Known issues

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

affects: All

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

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

affects: All versions targeting Django >= 5.2

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

affects: All

gotchaWhile `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'.

affects: All

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

affects: Versions targeting Django 5.2 and later

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'django_upgrade'

The `django-upgrade` package is not installed in the active Python environment, or the environment where it's installed is not the one being used.

fix

Install the package using pip: `pip install django-upgrade`

missing 1 required positional argument: 'on_delete'

When upgrading to Django 2.0 and later, `on_delete` is a mandatory argument for `ForeignKey` and `OneToOneField` definitions in Django models, which was not strictly enforced in earlier versions.

fix

Run `django-upgrade` to automatically add `on_delete` arguments, typically `models.CASCADE`, `models.SET_NULL`, or `models.PROTECT`, to your ForeignKey and OneToOneField definitions: `django-upgrade .`

Specifying a namespace in include() without providing an app_name

From Django 2.0 onwards, if you use the `include()` function with a namespace in your `urls.py` without also defining an `app_name` in the included URL patterns, Django raises this error to ensure clarity in URL resolution.

fix

Run `django-upgrade` to automatically add `app_name` attributes to your `urls.py` files or pass the `app_name` explicitly in the `include()` call: `django-upgrade .`

ImportError: cannot import name 'utc' from 'django.utils.timezone'

The `utc` constant in `django.utils.timezone` was deprecated in Django 4.1 and removed in later versions, requiring the use of `datetime.timezone.utc` instead.

fix

Run `django-upgrade` to automatically replace `from django.utils.timezone import utc` with `from datetime import timezone; utc = timezone.utc` or similar fixes: `django-upgrade .`

Upgrade

Version history

1.30.0latest on PyPI · released Feb 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/adamchainz/django-upgrade ↗

packagehttps://pypi.org/project/django-upgrade/ ↗

docshttps://django-upgrade.readthedocs.io/ ↗

changeloghttps://django-upgrade.readthedocs.io/en/latest/changelog.html ↗