Install & Compatibility
Where this runs
tested against v2.2.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.665s · 38.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.599s · 39MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CORS
✓ from sanic_cors import CORS
cross_origin
✓ from sanic_cors import cross_origin
This quickstart demonstrates how to enable CORS globally for a Sanic application using `CORS(app)` and how to apply it to individual routes using the `@cross_origin()` decorator. It sets up a basic Sanic app with two routes and ensures CORS headers are correctly handled for preflight OPTIONS requests and actual data requests.
from sanic import Sanic, response
from sanic_cors import CORS, cross_origin
import os
app = Sanic(__name__)
# Enable CORS for the entire application (or specify options)
CORS(app, origins="*", allow_headers="*", expose_headers="*", automatic_options=True)
@app.route("/", methods=["GET"])
@cross_origin(origins=os.environ.get('ALLOWED_ORIGIN', '*')) # Decorator for specific route
async def hello_world(request):
return response.json({"message": "Hello from Sanic-CORS!"})
@app.route("/data", methods=["GET", "POST"])
# cross_origin() can be omitted if CORS(app) handles it globally
async def get_data(request):
if request.method == "GET":
return response.json({"data": "Some public data"})
elif request.method == "POST":
return response.json({"status": "Data received"})
if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000)
Debug
Known issues
breakingSanic-CORS v2.0.0 removed compatibility with Sanic-Plugin-Toolkit (SPTK) and Sanic-Plugins-Framework (SPF). Code relying on these prior integration methods will break.fixMigrate your application to Sanic v21.12+ and update your Sanic-CORS usage to the direct API provided in v2.0.0, removing SPTK/SPF related configurations.
affects: >=2.0.0
breakingSanic-CORS v1.0.0 dropped support for Sanic versions older than 21.3. Attempting to use v1.0.0+ with older Sanic versions will lead to incompatibilities.fixFor Sanic versions <= 21.3, you must use the Sanic-CORS `0.10.x` branch (e.g., `pip install sanic-cors==0.10.0.post3`). Otherwise, upgrade Sanic to v21.3 or newer.
affects: >=1.0.0
gotchaCompatibility issues can arise with specific Sanic and Sanic-Ext versions due to changes in middleware handling or internal APIs. For example, Sanic-CORS 2.2.0 was needed for Sanic v22.9.0, and 2.1.0 for Sanic-Ext v22.6.0+.fixAlways check the Sanic-CORS release notes for specific compatibility updates before upgrading Sanic or Sanic-Ext. Ensure you're on the latest compatible version of Sanic-CORS.
affects: All versions, specific to Sanic/Sanic-Ext releases
gotchaThe `Vary` header behavior was improved in v2.2.0. Previously, `Vary 'Origin'` might overwrite existing `Vary` headers on a response, leading to unexpected caching behavior.fixUpgrade to Sanic-CORS v2.2.0 or newer to ensure `Vary 'Origin'` is correctly appended to any existing `Vary` header string.
affects: <2.2.0
Errors
Common errors & fixes
No 'Access-Control-Allow-Origin' header is present on the requested resource.
The CORS headers are not being sent by the Sanic server, often due to misconfiguration or `sanic-cors` not being applied to the specific route or application.
fixEnsure `CORS(app)` is called at the application level before routes are registered, or that `@cross_origin()` is applied to the specific route handler. Verify the `origins` parameter in `CORS()` or `@cross_origin()` allows the client's origin (e.g., `origins="*"` for development, or a specific domain).
405 Method Not Allowed (for OPTIONS requests)
Sanic is not correctly handling the CORS preflight OPTIONS request, indicating `sanic-cors` is not intercepting or correctly processing it.
fixEnsure `automatic_options=True` is passed to `CORS(app)` or `@cross_origin()`. This is often the default, but explicitly setting it can resolve issues. Also, ensure `CORS(app)` is called before any blueprints or routes that require CORS are registered, to allow the middleware to activate correctly.
AttributeError: 'Request' object has no attribute 'ctx'
This error can occur in older Sanic versions or specific setups where `sanic-cors` expects `request.ctx` but it's not available in the request context.
fixThis often points to a Sanic version incompatibility. Upgrade Sanic to a more recent version (e.g., Sanic 19.9+ or 21.3+). If upgrading Sanic is not feasible, you might need to use an older compatible `sanic-cors` version (e.g., `0.10.x` for Sanic <= 21.3).
Upgrade
Version history
2.2.0latest on PyPI · released Oct 7, 2022
Audit
Dependencies
sanicrequiredCore web framework integration
sanic-extoptionalCompatibility for specific versions (>=22.6.0 required sanic-cors 2.1.0+)
packagingrequiredReplaced distutils for version parsing since 2.1.0