Description

=================== django-cors-headers =================== .. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/django-cors-headers/main.yml.svg?branch=main&style=for-the-badge :target: https://github.com/adamchainz/django-cors-headers/actions?workflow=CI .. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge :target: https://github.com/adamchainz/django-cors-headers/actions?workflow=CI .. image:: https://img.shields.io/pypi/v/django-cors-headers.svg?style=for-the-badge :target: https://pypi.org/project/django-cors-headers/ .. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge :target: https://github.com/psf/black .. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge :target: https://github.com/pre-commit/pre-commit :alt: pre-commit A Django App that adds Cross-Origin Resource Sharing (CORS) headers to responses. This allows in-browser requests to your Django application from other origins. ---- **Improve your Django and Git skills** with `my books <https://adamj.eu/books/>`__. ---- About CORS ---------- Adding CORS headers allows your resources to be accessed on other domains. It's important you understand the implications before adding the headers, since you could be unintentionally opening up your site's private data to others. Some good resources to read on the subject are: * Julia Evans' `introductory comic <https://drawings.jvns.ca/cors/>`__ and `educational quiz <https://questions.wizardzines.com/cors.html>`__. * Jake Archibald’s `How to win at CORS <https://jakearchibald.com/2021/cors/>`__ * The `MDN Article <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_ * The `web.dev Article <https://web.dev/articles/cross-origin-resource-sharing>`_ * The `Wikipedia Page <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_ Requirements ------------ Python 3.9 to 3.14 supported. Django 4.2 to 6.0 supported. Setup ----- Install from **pip**: .. code-block:: sh python -m pip install django-cors-headers and then add it to your installed apps: .. code-block:: python INSTALLED_APPS = [ ..., "corsheaders", ..., ] Make sure you add the trailing comma or you might get a ``ModuleNotFoundError`` (see `this blog post <https://adamj.eu/tech/2020/06/29/why-does-python-raise-modulenotfounderror-when-modifying-installed-apps/>`__). You will also need to add a middleware class to listen in on responses: .. code-block:: python MIDDLEWARE = [ ..., "corsheaders.middleware.CorsMiddleware", "django.middleware.common.CommonMiddleware", ..., ] ``CorsMiddleware`` should be placed as high as possible, especially before any middleware that can generate responses such as Django's ``CommonMiddleware`` or Whitenoise's ``WhiteNoiseMiddleware``. If it is not before, it will not be able to add the CORS headers to these responses. About ----- **django-cors-headers** was created in January 2013 by Otto Yiu. It went unmaintained from August 2015 and was forked in January 2016 to the package `django-cors-middleware <https://github.com/zestedesavoir/django-cors-middleware>`_ by Laville Augustin at Zeste de Savoir. In September 2016, Adam Johnson, Ed Morley, and others gained maintenance responsibility for **django-cors-headers** (`Issue 110 <https://github.com/adamchainz/django-cors-headers/issues/110>`__) from Otto Yiu. Basically all of the changes in the forked **django-cors-middleware** were merged back, or re-implemented in a different way, so it should be possible to switch back. If there's a feature that hasn't been merged, please open an issue about it. **django-cors-headers** has had `40+ contributors <https://github.com/adamchainz/django-cors-headers/graphs/contributors>`__ in its time; thanks to every one of them. Configuration ------------- Configure the middleware's behaviour in your Django settings. You must set at least one of three following settings: * ``CORS_ALLOWED_ORIGINS`` * ``CORS_ALLOWED_ORIGIN_REGEXES`` * ``CORS_ALLOW_ALL_ORIGINS`` ``CORS_ALLOWED_ORIGINS: Sequence[str]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A list of origins that are authorized to make cross-site HTTP requests. The origins in this setting will be allowed, and the requesting origin will be echoed back to the client in the |access-control-allow-origin header|__. Defaults to ``[]``. .. |access-control-allow-origin header| replace:: ``access-control-allow-origin`` header __ https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin An Origin is defined by `the CORS RFC Section 3.2 <https://tools.ietf.org/html/rfc6454#section-3.2>`_ as a URI scheme + hostname + port, or one of the special values ``'null'`` or ``'file://'``. Default ports (HTTPS = 443, HTTP = 80) are optional. The special value ``null`` is sent by the browser