Django "settings are not configured" / DJANGO_SETTINGS_MODULE in CI

Django needs to know which settings module to load via the DJANGO_SETTINGS_MODULE env var (or an explicit settings.configure()). In CI it’s often unset, so any Django import or management command fails before doing anything.

What this error means

A management command, script, or test that touches Django raises ImproperlyConfigured: Requested setting ..., but settings are not configured. You must ... define the environment variable DJANGO_SETTINGS_MODULE.

Python traceback

django.core.exceptions.ImproperlyConfigured: Requested setting INSTALLED_APPS,
but settings are not configured. You must either define the environment variable
DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

Common causes

DJANGO_SETTINGS_MODULE not set in CI

Locally a .env, manage.py, or your shell exports it; the CI job doesn’t, so Django has no settings module to import.

Settings module not importable

The variable is set but points at a dotted path that isn’t on sys.path (wrong working directory, project not installed), so the import fails.

How to fix it

Set the settings module env var

Terminal

export DJANGO_SETTINGS_MODULE=myproject.settings.ci
python manage.py migrate --check

Let pytest-django provide it

For test runs, declare it in pytest config so you don’t rely on the ambient env.

pyproject.toml

[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "myproject.settings.ci"

Confirm the module imports

Run python -c "import myproject.settings.ci" from the CI working directory.
If it fails, pip install -e . or run from the repo root so the package is importable.
Use a dedicated CI settings module rather than dev/prod settings.

How to prevent it

Export DJANGO_SETTINGS_MODULE (or set it in pytest config) in every CI job.
Use a CI-specific settings module with test-safe values.
Install the project so the settings dotted path always resolves.