Starlette Context

0.5.1 · active · verified Sat Apr 11

Starlette Context is a middleware for Starlette that provides a request-scoped data store, allowing you to store and access context data throughout the request lifecycle. It is commonly used to enrich logs with request-specific identifiers like `x-request-id` or `x-correlation-id` without explicit parameter passing. The current version is 0.5.1, released on February 28, 2026, and the library maintains an active release cadence.

Warnings

breaking Python 3.9 and Python 3.8 support has been dropped in recent versions. Version 0.5.0 requires Python 3.10+, and v0.4.0 required Python 3.9+. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or higher.
breaking Support for Starlette versions below 0.27.0 was dropped in `starlette-context` v0.4.0. Ensure your Starlette installation is up-to-date.
Fix: Upgrade Starlette to version 0.27.0 or newer (e.g., `pip install 'starlette>=0.27.0'`).
breaking In v0.5.1, the `HeaderKeys` enum was changed to `StrEnum` to ensure consistent `str()` behavior across Python versions (e.g., `str(HeaderKeys.api_key)` now consistently returns `'X-API-Key'`). Code relying on the prior inconsistent string representation (e.g., `'HeaderKeys.api_key'` on Python 3.11+) might break.
Fix: Review any code that explicitly converts `HeaderKeys` enum members to strings and ensure it expects the header key string (e.g., 'X-API-Key').
gotcha Accessing the `context` object outside of a request-response cycle (i.e., when no middleware is active or `request_cycle_context` is not used) will raise a `ContextDoesNotExistError`. This can happen during application startup or in background tasks not tied to a request.
Fix: Always use `if context.exists():` before accessing `context.data` or `context[...]` outside of a guaranteed request cycle. For tests or specific asynchronous tasks, wrap the code with `async with request_cycle_context():` to establish a temporary context.
breaking As of v0.3.2, attempting to access a non-existent context now raises `ContextDoesNotExistError` instead of a generic `RuntimeError`. While `ContextDoesNotExistError` inherits from `RuntimeError` for backward compatibility, specific `except RuntimeError` blocks might need to be updated to `except ContextDoesNotExistError:` for clearer exception handling.
Fix: Update exception handling for context access from `except RuntimeError` to `except ContextDoesNotExistError` where applicable.
breaking Version 0.3.0 introduced a 'small refactor of the base plugin' which involved moving directories and removing a redundant method. This was noted as 'potentially breaking changes' for users upgrading from very early versions who might have custom plugins or direct imports to internal plugin modules.
Fix: If migrating from versions older than 0.3.0 and using custom plugins or internal plugin imports, review the changelog and documentation for `v0.3.0` for necessary adjustments.

Install

pip install starlette-context Install stable version

Imports

ContextMiddleware

from starlette_context.middleware import ContextMiddleware

RawContextMiddleware
```
from starlette_context.middleware import RawContextMiddleware
```
Use RawContextMiddleware for streaming or file responses, or when avoiding BaseHTTPMiddleware limitations.
context
```
from starlette_context import context
```
The context object is directly available from the top-level package.
plugins
```
from starlette_context import plugins
```
Provides access to built-in plugins like RequestIdPlugin and CorrelationIdPlugin.
request_cycle_context
```
from starlette_context import request_cycle_context
```
A context manager for manual context management, often used in tests or FastAPI dependencies.

Quickstart

This example demonstrates how to set up `ContextMiddleware` with basic plugins (`RequestIdPlugin`, `CorrelationIdPlugin`) and access/modify the `context` object within a Starlette route. When you access '/', the response will include the generated request and correlation IDs, along with any custom data added to the context. To run, save as `example.py` and execute `uvicorn example:app --port 8000`.

import uvicorn
from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.responses import JSONResponse
from starlette.routing import Route
from starlette_context import context, plugins
from starlette_context.middleware import ContextMiddleware

async def homepage(request):
    # Access and modify context data
    context["user_id"] = "123"
    context["custom_data"] = "Hello from Starlette Context!"
    return JSONResponse(context.data)

routes = [
    Route("/", endpoint=homepage)
]

middleware = [
    Middleware(
        ContextMiddleware,
        plugins=(
            plugins.RequestIdPlugin(),
            plugins.CorrelationIdPlugin(),
        )
    )
]

app = Starlette(routes=routes, middleware=middleware)

if __name__ == "__main__":
    # Run with `uvicorn example:app --port 8000`
    uvicorn.run(app, host="0.0.0.0", port=8000)

view raw JSON →