Modern Python services often process many requests and background jobs at the same time. An asynchronous application can pause one coroutine, run another, and return to the first one later. This behavior makes ordinary global variables unsafe for request-specific information. A request identifier, tenant name, locale, or trace value can be overwritten by another task before the original task finishes. The contextvars module provides variables whose values belong to the current execution context, allowing concurrent tasks to keep separate metadata even when they share the same process and event loop.
This guide explains how ContextVar works, why tokens matter, how the module integrates with asyncio, and how to use it for structured logging and tracing. You can combine these ideas with our guides about observability with structlog, Pydantic Settings, tomllib configuration, and singledispatch.
Why global variables are risky
Consider a web server that stores the current request identifier in a global variable. Request A sets the identifier and waits for a database query. During that wait, request B changes the same variable. When request A resumes, a log message may contain the identifier from request B. The problem can remain invisible in unit tests because they usually execute one scenario at a time. It appears only under concurrency, where the incorrect metadata makes production incidents difficult to investigate.
Passing the identifier through every function avoids global state but creates another problem. Many functions do not use the value directly; they only forward it to a deeper layer. Signatures become noisy, and infrastructure details spread into business logic. A context variable makes lightweight metadata available to the current flow without requiring every intermediate function to accept another argument.
Creating and reading a ContextVar
Create a ContextVar once at module level and give it a descriptive name. You can provide a default for optional metadata. Calling get returns the value associated with the current context. Calling set changes the value only for that context. If no default exists and no value has been set, get raises LookupError. This strict behavior is useful when the application must initialize the context before doing any work.
Do not create a new ContextVar inside every request handler. The variable object should be stable, while its value changes from one context to another. Type annotations can document the expected value and help static analysis tools detect mistakes.
Restore values with tokens
The set method returns a token representing the previous state. Store this token and pass it to reset when the temporary operation finishes. Always place reset in a finally block so exceptions do not leave stale metadata behind. A token is better than assigning a fallback value manually because nested layers may already have established a value. Reset restores the exact earlier state, including the absence of a value.
This pattern is important in servers and workers that remain alive for a long time. Without cleanup, a task reused by framework code may carry an identifier into unrelated work. A small helper or context manager can standardize the set, try, finally, and reset sequence throughout the project.
Isolation in asyncio
Context variables are designed to work with asyncio tasks. When separate tasks set different values, each task reads its own value even when execution switches at await points. This is the key difference between a ContextVar and an ordinary module-level variable. The Python runtime manages the context associated with each task and restores it when that task resumes.
The official contextvars documentation describes the API and its relationship to contexts. The asyncio task documentation explains how coroutines are scheduled. Reading both helps clarify why context-local state remains stable while tasks interleave.
Correlation IDs and structured logs
A common use case is a correlation ID. At the beginning of an HTTP request, the application accepts an incoming identifier or generates a new one. It stores that value in a ContextVar. Logging filters, structlog processors, database helpers, and outbound HTTP clients can then read the same identifier without requiring it as a parameter in every call.
The result is a consistent field across all events generated by the request. Operators can search logs for one correlation ID and reconstruct the complete flow. The same pattern works for trace IDs, a tenant marker, a locale, or a technical actor. Keep these values short and avoid storing complete user records or large objects.
Context is not business storage
Context variables should hold cross-cutting metadata, not core business data. Function arguments remain the clearest choice for values that determine business results. Databases and caches remain the correct place for persistent state. Dependency injection remains useful for explicit service dependencies. ContextVar should not become a hidden container where any function can retrieve arbitrary data.
A useful rule is to ask whether the value is needed mainly for logging, tracing, auditing, localization, or request-scoped infrastructure. If the answer is yes, context may be appropriate. If the value changes the business decision of a function, make it explicit in the function signature whenever possible.
Threads and executors
Each thread maintains its own context stack. Asyncio task propagation is usually automatic, but manual thread pools and third-party executors require attention. The copy_context function captures the current context and can run a callable inside that captured state. Use it when moving blocking work to a custom thread and when the worker must keep request metadata.
Do not assume that every library propagates context. Create an integration test when combining asyncio, callbacks, custom executors, and background workers. The test should set an identifier before dispatching work and confirm that the worker reads the expected value.
Testing context-aware components
Tests must clean up after themselves. A fixture can set a value before a test and reset the token afterward. This prevents one test from affecting another. Also include a concurrency test that launches two tasks with different values, introduces an await point, and confirms that each task still reads its original value.
Test missing context as well. If the application requires a tenant or request identifier, verify that code fails clearly when initialization is forgotten. If a default is intentional, test the background-job scenario that relies on that default.
Common mistakes
The most frequent mistake is forgetting reset. Another is storing mutable objects and changing them in place, which can create confusing shared behavior. Prefer immutable strings, numbers, or small frozen structures. Avoid using context as a security boundary: it isolates flows but does not encrypt values or stop code within the same flow from reading them.
A default value can also hide bugs. A generic value such as unknown may make logs look valid even though middleware failed to initialize the context. For mandatory metadata, no default and a clear error may be safer.
Recommended project design
Place context variables in a dedicated module and expose narrow helper functions such as get_request_id and request_context. The context manager should set the value, yield control, and reset the token in finally. Framework middleware can call this helper at request entry, while tests can use the same API. Centralization improves documentation and prevents slightly different cleanup patterns from appearing throughout the codebase.
Conclusion
Python contextvars provides safe request-scoped metadata for concurrent applications. It prevents collisions caused by globals, avoids excessive parameter plumbing, and integrates naturally with asyncio, structured logging, tracing, and auditing. Declare variables once, restore temporary values with tokens, keep contextual data lightweight, and test concurrent execution. With these practices, an application gains reliable observability without sacrificing isolation between requests and background jobs.
