Registry / web-framework / django-cors-headers

django-cors-headers

library4.9.0pypypi✓ verified 29d ago

django-cors-headers is a Django application that simplifies the handling of server headers required for Cross-Origin Resource Sharing (CORS). It provides a robust and flexible solution to manage cross-origin requests, allowing Django applications to securely interact with frontend applications hosted on different domains. The current version is 4.9.0, and it maintains an active release cadence with regular updates and community support.

web-framework auth-security

pip install django-cors-headers

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · DJANGO-CORS-HEADER

django-cors-headers

web-frameworkpythonv4.9.0

Install

3.5s avg

Import

788ms

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.830s · 66.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.5s · import 0.746s · 67MB

66MB installed

● package 66MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CorsMiddleware

✓ from corsheaders.middleware import CorsMiddleware

To quickly enable CORS, install the package, then add `corsheaders` to your `INSTALLED_APPS` and `CorsMiddleware` to the top of your `MIDDLEWARE` list in `settings.py`. Finally, configure `CORS_ALLOWED_ORIGINS` with a list of allowed frontend domains. For development, `CORS_ALLOW_ALL_ORIGINS = True` can be used temporarily but is not recommended for production due to security risks. Remember that middleware order is crucial for correct functionality.

# settings.py INSTALLED_APPS = [ # ... other apps 'corsheaders', # ... ] MIDDLEWARE = [ 'corsheaders.middleware.CorsMiddleware', 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware', # ... other middleware ] # Whitelist specific origins. In production, avoid CORS_ALLOW_ALL_ORIGINS = True. CORS_ALLOWED_ORIGINS = [ "http://localhost:3000", "http://127.0.0.1:3000", # Add your frontend domains here, e.g., "https://yourfrontend.com" ] # Optional: Allow credentials (cookies, auth headers) to be sent cross-origin # CORS_ALLOW_CREDENTIALS = True # Optional: If you need to allow all origins for development (use with caution in production!) # CORS_ALLOW_ALL_ORIGINS = False # Set to True for development, but remove for production # Example for allowing specific HTTP methods if you deviate from default allowed methods # CORS_ALLOW_METHODS = [ # 'DELETE', # 'GET', # 'OPTIONS', # 'PATCH', # 'POST', # 'PUT', # ]

Debug

Known issues

gotchaMiddleware order is critical. `CorsMiddleware` must be placed at the very top of your `MIDDLEWARE` list, before any other middleware (like `SecurityMiddleware` or `CsrfViewMiddleware`) that might block preflight `OPTIONS` requests or prevent CORS headers from being added correctly.

fix

Ensure 'corsheaders.middleware.CorsMiddleware' is the first entry in your MIDDLEWARE setting in settings.py.

affects: All versions

breakingSince version 3.0.0, `CORS_ORIGIN_WHITELIST` was renamed to `CORS_ALLOWED_ORIGINS`. Additionally, allowed origins now *require* URI schemes (e.g., 'https://example.com' instead of 'example.com') and optionally ports, fixing a security issue with scheme-mixing.

fix

Update your settings to use `CORS_ALLOWED_ORIGINS` instead of `CORS_ORIGIN_WHITELIST`, and ensure all origins include their full URI scheme (e.g., 'http://localhost:3000').

affects: >=3.0.0

gotchaAvoid using `CORS_ALLOW_ALL_ORIGINS = True` in production environments as it poses a significant security risk by allowing any domain to access your resources. Be specific with `CORS_ALLOWED_ORIGINS`.

fix

In production, always use `CORS_ALLOWED_ORIGINS` to specify a list of trusted origins. For dynamic origins, consider `CORS_ALLOWED_ORIGIN_REGEXES`.

affects: All versions

gotchaIf you are sending credentials (like cookies or authorization headers) from your frontend, you must set `CORS_ALLOW_CREDENTIALS = True` in your Django settings and also configure your frontend client (e.g., `withCredentials: true` for Axios or `credentials: 'include'` for Fetch API). Additionally, be aware of Django's `SESSION_COOKIE_SAMESITE` setting (default 'Lax' in Django 2.1+) which might prevent session cookies from being sent cross-domain; change to 'None' if needed.

fix

Set `CORS_ALLOW_CREDENTIALS = True` in `settings.py` and configure your frontend to send credentials. Adjust `SESSION_COOKIE_SAMESITE = 'None'` if necessary for session cookies to be sent cross-domain.

affects: All versions

gotchaIf you are serving static files or other assets from a different domain (e.g., a CDN or cloud storage like GCP), CORS headers must be configured on the *server hosting those assets*, not just in your Django application. `django-cors-headers` only handles headers for requests served by Django itself.

fix

Configure CORS policies directly on your CDN, cloud storage bucket, or web server (Nginx/Apache) for assets served from those locations.

affects: All versions

deprecatedThe `CORS_REPLACE_HTTPS_REFERER` setting and `CorsPostCsrfMiddleware` were removed. For making CSRF checks pass for CORS requests, Django's `CSRF_TRUSTED_ORIGINS` setting is the preferred and modern solution.

fix

Remove `CORS_REPLACE_HTTPS_REFERER` and `CorsPostCsrfMiddleware`. Configure `CSRF_TRUSTED_ORIGINS` in your `settings.py` with your trusted frontend origins.

affects: >=3.1.0

Errors

Common errors & fixes

ImproperlyConfigured: Error importing module corsheaders.middleware.CorsMiddlewaredjango.middleware.common: "No module named CorsMiddlewaredjango.middleware.common"

A missing comma between middleware classes in the MIDDLEWARE setting leads to incorrect concatenation of strings.

fix

Ensure each middleware class in the MIDDLEWARE setting is separated by a comma.

Access to fetch at 'http://localhost:8000/api/students' from origin 'http://localhost:5173' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

The CORS policy blocks requests from unallowed origins due to misconfiguration or missing headers.

fix

Install and configure django-cors-headers, add 'corsheaders.middleware.CorsMiddleware' to MIDDLEWARE, and set CORS_ALLOWED_ORIGINS or CORS_ALLOW_ALL_ORIGINS in settings.py.

TypeError: Signal.__init__() got an unexpected keyword argument 'providing_args'

The providing_args argument was removed in Django 4.0, causing compatibility issues with older versions of django-cors-headers.

fix

Upgrade django-cors-headers to version 3.10.1 or later to ensure compatibility with Django 4.0 and above.

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://<website>.com. This can be fixed by moving the resource to the same domain or enabling CORS.

The server does not include the 'Access-Control-Allow-Origin' header, leading to blocked cross-origin requests.

fix

Install django-cors-headers, add 'corsheaders.middleware.CorsMiddleware' to MIDDLEWARE, and configure CORS_ALLOWED_ORIGINS or CORS_ALLOW_ALL_ORIGINS in settings.py.

No module named 'corsheaders'

The django-cors-headers package is not installed or not properly installed in the Python environment.

fix

Install the package using pip: pip install django-cors-headers.

Upgrade

Version history

4.9.0latest on PyPI · released Sep 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/adamchainz/django-cors-headers ↗

packagehttps://pypi.org/project/django-cors-headers/ ↗

changeloghttps://github.com/adamchainz/django-cors-headers/blob/main/CHANGELOG.rst ↗