Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Django cannot import corsheaders (django-cors-headers)

ErrorModuleNotFoundError: No module named 'corsheaders'

Short answer

The pip package is django-cors-headers, but the module Django imports is corsheaders. The error means the Python that runs Django cannot find that module: it was installed in another environment, you installed a package with the wrong name, or INSTALLED_APPS is missing a comma.

  • Applies to Django 5.2, django-cors-headers (current), Python 3.11+
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the exact Python that runs your site whether it can see the package. Use the interpreter from your service or virtual environment, not whichever python is first on your path.

    /path/to/venv/bin/python -m pip show django-cors-headers
    /path/to/venv/bin/python -c "import corsheaders; print(corsheaders.__file__)"
  2. 2Match what you see, then jump to its fix

    1. 1pip install succeeds, yet the web server still fails (common on a server with several Python installs)The package is installed in a different Python environmentFix
    2. 2pip show django-cors-headers prints nothingThe wrong package name was installedFix
    3. 3The package is installed and imports in a shell, but Django still reports the missing moduleINSTALLED_APPS lacks a comma after the entryFix

What does the error look like?

  • ModuleNotFoundError: No module named 'corsheaders'
  • ImportError: No module named corsheaders

Cause 1 of 3

The package is installed in a different Python environment

1Check

Compare the interpreter your service uses with the one pip belongs to.

which python pip
systemctl cat gunicorn | grep -i ExecStart

2Fix

Install with the same interpreter that runs Django. Using python -m pip guarantees that pairing.

/path/to/venv/bin/python -m pip install django-cors-headers

3Verify

Restart the service and import the module with that interpreter.

sudo systemctl restart gunicorn
/path/to/venv/bin/python -c "import corsheaders"

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The wrong package name was installed

1Check

The project's own page states that the pip package is django-cors-headers, while the module is corsheaders. Installing a package literally named corsheaders is a different thing.

python -m pip list | grep -i cors

2Fix

Install the right package and use corsheaders in settings.

python -m pip install django-cors-headers

3Verify

Import the module.

python -c "import corsheaders; print('ok')"

Confirmed by github.com

Did this fix it?

Cause 3 of 3

INSTALLED_APPS lacks a comma after the entry

1Check

The project's own page warns that leaving out the trailing comma after corsheaders can raise ModuleNotFoundError. Look at the neighbouring entries.

grep -n -B2 -A2 corsheaders settings.py

2Fix

Add the app with its trailing comma, and put the middleware before CommonMiddleware.

INSTALLED_APPS = [
    # ...
    "corsheaders",
]

MIDDLEWARE = [
    "corsheaders.middleware.CorsMiddleware",
    "django.middleware.common.CommonMiddleware",
    # ...
]

3Verify

Run Django's system check.

python manage.py check

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep dependencies in requirements.txt and install them with the same interpreter that serves the site.
  • Install with python -m pip, never a bare pip, on servers with more than one Python.
  • After adding a package, restart the app server, which loads modules only at start.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.