Install & Compatibility
Where this runs
tested against v2.12.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.960 runs
installs and imports cleanly · install 0.0s · import 0.676s · 43.5MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 4.3s · import 0.609s · 46MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_session
✓ from aiohttp_session import get_session
setup
✓ from aiohttp_session import setup
EncryptedCookieStorage
✓ from aiohttp_session.cookie_storage import EncryptedCookieStorage
RedisStorage
✓ from aiohttp_session.redis_storage import RedisStorage
Fernet
✓ from cryptography.fernet import Fernet
This quickstart demonstrates setting up a basic aiohttp.web application with session management using EncryptedCookieStorage. It initializes a Fernet key (generating one if not provided via environment variable, highlighting the need for persistence in production), registers the session middleware with `setup()`, and uses `get_session()` within a handler to store and retrieve user visit times. Run the server, then access `http://localhost:8080` in your browser to see session data persist.
import asyncio
import os
from cryptography import fernet
from aiohttp import web
from aiohttp_session import get_session, setup
from aiohttp_session.cookie_storage import EncryptedCookieStorage
async def handler(request):
session = await get_session(request)
last_visit = session.get('last_visit', 'Never')
session['last_visit'] = str(request.app['current_time'])
text = f"Last visited: {last_visit}\nHello, current time is {session['last_visit']}"
return web.Response(text=text)
async def make_app():
app = web.Application()
# Generate a Fernet key. In production, this should be stored securely
# and loaded from environment variables or a secret management system.
# Using a dummy key for demonstration purposes.
fernet_key_str = os.environ.get('AIOHTTP_SESSION_KEY', None)
if fernet_key_str is None:
# WARNING: DO NOT generate a new key on every app startup in production!
# A new key invalidates all existing sessions. Load from a persistent source.
fernet_key = fernet.Fernet.generate_key()
print(f"Generated new Fernet key (for demo only): {fernet_key.decode()}\nSet AIOHTTP_SESSION_KEY env var in production.")
else:
fernet_key = fernet_key_str.encode()
f = fernet.Fernet(fernet_key)
setup(app, EncryptedCookieStorage(f))
app['current_time'] = 'Not set yet'
app.router.add_get('/', handler)
return app
async def main():
app = await make_app()
runner = web.AppRunner(app)
await runner.setup()
site = web.TCPSite(runner, 'localhost', 8080)
await site.start()
print("Server started at http://localhost:8080")
try:
while True:
app['current_time'] = asyncio.get_event_loop().time()
await asyncio.sleep(1)
except asyncio.CancelledError:
pass
finally:
await runner.cleanup()
if __name__ == '__main__':
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Server stopped.")
Errors
Common errors & fixes
RuntimeError: Cannot install aiohttp_session[aioredis] without aioredis library
Prior to v2.12.0, the `aioredis` extra explicitly required the `aioredis` package. Post v2.12.0, it shifted to `redis`.
fixIf on `aiohttp-session < 2.12.0`, ensure `pip install aioredis`. If on `aiohttp-session >= 2.12.0`, ensure `pip install redis` or `pip install aiohttp-session[aioredis]`.
cryptography.fernet.InvalidToken: Message too short
This error often indicates that the `EncryptedCookieStorage` received a cookie it couldn't decrypt. Common causes include a corrupted session cookie, or the application's encryption key changing between server restarts.
fixVerify that the Fernet encryption key used by `EncryptedCookieStorage` is consistent across all application instances and restarts. Ensure that `Fernet.generate_key()` is not called repeatedly in production. Users with invalid cookies will simply receive a new session.
TypeError: session_middleware() got an unexpected keyword argument 'storage'
The `session_middleware` function is typically called as `session_middleware(storage_instance)` and then passed to `app.middlewares`. If `setup(app, storage_instance)` is used, you generally don't interact with `session_middleware` directly.
fixUse `setup(app, storage_instance)` to configure the session middleware, or pass `session_middleware(storage_instance)` directly to the `middlewares` list when creating `web.Application`.
KeyError: 'AIOHTTP_SESSION' (or other cookie name) or session data not persisting between requests.
This usually means the session middleware is not correctly registered or the `aiohttp.web.Application` instance receiving requests is not the one configured with the session middleware.
fixEnsure `aiohttp_session.setup(app, storage)` is called on the `web.Application` instance that handles your routes, or that `session_middleware(storage)` is properly included in the `middlewares` list of `web.Application`.
Upgrade
Version history
2.12.1latest on PyPI · released Sep 25, 2024
Audit
Dependencies
aiohttprequiredCore web framework dependency.
cryptographyoptionalRequired for EncryptedCookieStorage. Installed via 'aiohttp-session[secure]' extra.
redisoptionalRequired for RedisStorage. Installed via 'aiohttp-session[aioredis]' extra (since v2.12.0).
aiomcacheoptionalRequired for MemcachedStorage.