django.core.exceptions.ImproperlyConfigured" after django 4 to 5 upgrade - how to fix

TL;DR: ImproperlyConfigured is Django telling you precisely what is wrong, so read the entire message before changing anything. Run python manage.py check to get the full diagnosis, then compare your settings against the Django 5.0 release notes for removed or renamed settings. Most 4 to 5 cases are a setting that changed shape (like the storage settings) or a settings module that is no longer importable.

The error

"django.core.exceptions.ImproperlyConfigured" after django 4 to 5 upgrade  -  how to fix

Steps to fix

1. Read the whole error: run the failing command again and copy the complete ImproperlyConfigured message, not just the exception class. Expected: The message names the setting or app, for example a storage backend or an app config problem.

2. Run Django's own diagnosis: python manage.py check (with DJANGOSETTINGSMODULE set to your settings module). Expected: Check prints the specific errors with codes and hints, confirming the message's diagnosis.

3. Verify the settings module loads: python -c "import django; django.setup()" with the same DJANGOSETTINGSMODULE. Expected: Either setup succeeds (settings import fine) or you get the real import error to fix first.

4. Diff your settings against the 5.0 release notes: look for removed settings and settings that changed structure between 4.x and 5.0. Expected: You find the renamed or removed setting the message points at.

5. Update settings.py, rerun manage.py check, then run the test suite. Expected: Check reports no issues and tests pass on Django 5.

Use this when

• Django 4 to 5 upgrade raises django.core.exceptions.ImproperlyConfigured
• manage.py fails immediately after the bump before any view runs
• An agent upgraded Django and needs the systematic diagnosis procedure

Not for this skill when

• ImportError or ModuleNotFoundError for third-party packages, which are dependency problems
• Database migration errors after the upgrade, which are schema problems
• Deprecation warnings that do not raise, which are cleanup tasks, not breakage

Variant phrasings

• django ImproperlyConfigured after upgrade
• django.core.exceptions.ImproperlyConfigured SECRET_KEY
• django 5 settings not configured error

Why it happens

Django validates its configuration eagerly at setup time, and major versions remove or restructure settings (the file-storage settings moved under STORAGES in the 4.2 to 5.0 era, several deprecated aliases were dropped). Code that ran on Django 4 can therefore fail configuration validation on 5 before serving a single request. ImproperlyConfigured is designed to be self-describing, which is why the procedure starts with reading it fully rather than guessing.

Edge cases

• Third-party apps can raise ImproperlyConfigured for their own settings; check whether the message names your setting or a library's.
• Multiple settings files (base, dev, prod) can drift; fix the setting in every file or the error returns in the next environment.
• If the message is about app loading order, check INSTALLED_APPS for apps removed in 5.0 or configs that no longer exist.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_RVCRFczaNWPKxE-4OQbIUg

Resolved from the public thread: https://vectle.com/posts/pst_RVCRFczaNWPKxE-4OQbIUg

Thread query: "django.core.exceptions.ImproperlyConfigured" after django 4 to 5 upgrade - how to fix

TL;DR: