Install & Compatibility
Where this runs
tested against v0.8.1 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.708s · 27.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.3s · import 0.622s · 29MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
aiohttp_cors
✓ import aiohttp_cors
✗ from aiohttp_cors import setup
The primary functions `setup` and `add` are typically accessed directly from the imported `aiohttp_cors` module.
CorsViewMixin
✓ from aiohttp_cors import CorsViewMixin
Used for enabling CORS on aiohttp.web.View classes.
This quickstart sets up a basic aiohttp web application and applies a permissive CORS policy to a '/hello' endpoint, allowing requests from any origin. It demonstrates how to initialize CORS for the application and then apply it to specific routes or resources. It also shows a commented-out section for applying CORS to all routes programmatically.
import aiohttp_cors
from aiohttp import web
async def handler(request):
return web.Response(text="Hello from CORS-enabled endpoint!")
async def main():
app = web.Application()
# Setup CORS for all origins, allowing all headers and methods
cors = aiohttp_cors.setup(app, defaults={
"*": aiohttp_cors.ResourceOptions(
allow_credentials=True,
expose_headers="*",
allow_headers="*",
allow_methods="*"
)
})
# Add a route and enable CORS for it
resource = cors.add(app.router.add_resource("/hello"))
resource.add_route("GET", handler)
# Alternatively, you can add CORS to existing routes directly
# For example, if you had:
# app.router.add_post("/data", data_handler)
# cors.add(app.router.get("/data"))
# To apply CORS to ALL existing routes:
# for route in list(app.router.routes()):
# if not route.is_cors_enabled():
# cors.add(route)
print("Server starting on http://localhost:8080")
runner = web.AppRunner(app)
await runner.setup()
site = web.TCPSite(runner, 'localhost', 8080)
await site.start()
await asyncio.Event().wait() # Keep server running
if __name__ == '__main__':
import asyncio
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Server stopped.")
Debug
Known issues
breakingaiohttp-cors has strict compatibility requirements with `aiohttp` and `Python` versions. As of v0.8.0, it requires `aiohttp>=3.9` and `Python>=3.9`. Earlier versions of aiohttp-cors were compatible with older aiohttp and Python versions, but upgrading both libraries simultaneously is often necessary.fixAlways check the `aiohttp-cors` `CHANGES.rst` or `setup.py` for precise `aiohttp` and `Python` version requirements when upgrading or setting up. Upgrade `aiohttp` and `Python` versions as needed.
affects: <0.8.0
gotchaCORS configuration must be explicitly applied to each route or resource you wish to expose. Simply initializing `aiohttp_cors.setup(app)` does not automatically enable CORS on all your application's routes.fixAfter `aiohttp_cors.setup(app, defaults=...)`, you must use `cors.add(app.router.add_resource(...))` or `cors.add(route)` for individual routes. If you want to enable CORS for all existing routes, iterate over `app.router.routes()` and call `cors.add(route)` for each.
affects: All versions
deprecatedThe use of `asyncio.coroutine` decorators for handlers is deprecated in Python 3.5+ in favor of `async def` syntax. While `aiohttp-cors` itself supports this, ensure your application handlers use modern async/await syntax.fixRefactor `asyncio.coroutine` decorated functions to use `async def` syntax for better readability and alignment with modern Python best practices. For example, `@asyncio.coroutine def my_handler(...)` becomes `async def my_handler(...)`.
affects: All versions (if using older Python syntax)
breakingIn `aiohttp-cors` v0.7.0, the web view check became implicit and type-based, and support for Python 3.4 was disabled. If you were relying on explicit view checks or using Python 3.4, this will break your application.fixEnsure your application is running on Python 3.5+ (preferably 3.9+ as per current requirements) and review any custom logic related to aiohttp views that might have been affected by the change to implicit type-based checking.
affects: 0.7.0 and later
Errors
Common errors & fixes
AttributeError: 'CORS' object has no attribute 'add'
This error occurs when attempting to use the 'add' method on a 'CORS' object, which does not have such a method.
fixEnsure that you are using the correct methods provided by the 'aiohttp-cors' library, such as 'setup' and 'add' on the 'CorsConfig' object returned by 'setup'.
ImportError: cannot import name 'CORS' from 'aiohttp_cors'
This error occurs when trying to import 'CORS' directly from 'aiohttp_cors', which does not expose a 'CORS' class.
fixImport 'setup' from 'aiohttp_cors' and use it to configure CORS in your application.
TypeError: setup() missing 1 required positional argument: 'app'
This error occurs when calling 'setup()' without passing the 'app' instance as an argument.
fixPass your 'app' instance to the 'setup()' function: 'cors = aiohttp_cors.setup(app)'.
TypeError: add() missing 1 required positional argument: 'route'
This error occurs when calling 'add()' without passing a route to be configured for CORS.
fixEnsure you pass the route to the 'add()' method: 'cors.add(app.router.add_route("GET", "/path", handler))'. AttributeError: 'Resource' object has no attribute 'add_route'
This error occurs when attempting to call 'add_route' on a 'Resource' object, which does not have such a method.
fixUse 'app.router.add_route' to add routes before configuring CORS.
Upgrade
Version history
0.8.1latest on PyPI · released Mar 31, 2025
Audit
Dependencies
aiohttprequiredCore dependency for aiohttp web applications, tightly coupled for version compatibility.