Guides / ModuleNotFoundError: No module named 'myproject.settings'

Peter van Doorn Django Cloud · Checked against Django 4.2 and newer, October 2026

ModuleNotFoundError: No module named 'myproject.settings'

The server starts and immediately dies with ModuleNotFoundError: No module named 'myproject.settings' or 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. Django can't find or import your settings module in the production process.

What it means

DJANGO_SETTINGS_MODULE holds the dotted path of your settings (for example myproject.settings). manage.py and wsgi.py set a default for it, so everything works locally. In production, a different entry point (gunicorn, a worker script, a cron command) may not set it, or sets it to a path that doesn't import from where the process starts.

Why it happens

1. The variable isn't set for the process that starts the app, and the file that is imported doesn't set a default.
2. The path is wrong. You renamed the project folder, moved to config.settings.production, or the value still says myproject.settings.
3. The working directory or PYTHONPATH is wrong, so Python can't see the project package. gunicorn must start from the folder that contains manage.py, or be told to with --chdir.
4. The module exists, but importing it fails inside. A missing dependency or a typo in settings produces ModuleNotFoundError for the inner module, which looks like the settings are missing. Read the traceback above the last line.
5. Case or a missing file. Settings.py versus settings.py works on macOS and fails on Linux. A file excluded by .dockerignore never reached the image.

The fix

First find the real error, by importing the module by hand, with the same environment and folder as the server:

cd /srv/app   # the folder with manage.py
DJANGO_SETTINGS_MODULE=myproject.settings python -c "import django; django.setup(); print('ok')"

If that prints the true traceback (a missing package, a bad import), fix that. If the module itself is missing, set the path explicitly where the server starts:

export DJANGO_SETTINGS_MODULE=myproject.settings
gunicorn myproject.wsgi:application --chdir /srv/app --bind 0.0.0.0:8000

Check that wsgi.py (or asgi.py) sets a default and that it matches:

# myproject/wsgi.py
import os

from django.core.wsgi import get_wsgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
application = get_wsgi_application()

With several settings files, select production through the environment and keep the default pointing at a safe one:

DJANGO_SETTINGS_MODULE=myproject.settings.production

Making it stick in production

• Use the same dotted path in manage.py, wsgi.py, asgi.py, the start command and your CI.
• List the module the server runs (myproject.wsgi:application) in your docs or Procfile, so renaming a folder is a visible change.
• Smoke-test the deployable artifact: build the image or package, then run python manage.py check --deploy inside it.
• If the failing import is a third-party package, see ModuleNotFoundError only after deploy.

Or skip it

Django Cloud finds your ASGI or WSGI application on its own, and you can change the build settings if your project is set up differently.

pip install djangocloud-cli
djangocloud deploy

Get startedSee pricing

Free plans are available for students, AWS Activate startups, open-source, non-profit and research projects. See how Django Cloud compares with other ways to host Django.

Django is a registered trademark of the Django Software Foundation. Django Cloud is not affiliated with or endorsed by it. Found a mistake in this guide? Tell us and we will fix it.