Python ContextVars vs Threading Local: Which to Use
Compare contextvars and threading.local for per-request state in Python, including async task isolation, context copying, and when to use each.

A web server handling concurrent requests needs to keep request-specific values isolated: the authenticated user, a trace ID, the active database transaction. In a threaded server, each thread runs one request at a time, so thread-local storage is a natural fit. In an async server, many requests share a single thread, so the isolation boundary has to move from the thread to the task. That shift is the core difference between contextvars and threading.local.
What threading.local Provides
threading.local creates an object whose attributes are stored per thread. Two threads setting the same attribute on the same instance see different values.
import threading
local = threading.local()
def worker(name):
local.name = name
print(f"{threading.current_thread().name}: {local.name}")
t1 = threading.Thread(target=worker, args=("alice",))
t2 = threading.Thread(target=worker, args=("bob",))
t1.start(); t2.start()
t1.join(); t2.join()Each thread gets its own copy of local.name. The instance itself is shared, but the attribute storage is keyed by thread identity. This works well when the concurrency model is purely thread-based and each thread handles exactly one logical unit of work at a time.
What contextvars.ContextVar Provides
ContextVar, added in Python 3.7, stores a value in the current execution context. A context is an immutable mapping of ContextVar objects to their values. You set a value with .set() and read it with .get().
import contextvars
request_id = contextvars.ContextVar("request_id", default=None)
def handle_request():
request_id.set("req-42")
print(request_id.get())
handle_request()
print(request_id.get()) # None, outside the contextThe default parameter supplies the value when the variable has not been set in the current context. Unlike threading.local, ContextVar does not care about threads. It cares about contexts, which are copied and passed to new tasks.
Why threading.local Breaks in Async Code
The failure mode is subtle. In asyncio, multiple tasks run on the same thread. When a coroutine awaits, the event loop may switch to another task. If that task reads a threading.local attribute set by the first task, it sees the value, because both tasks share the same thread.
import asyncio
import threading
local = threading.local()
async def set_user():
local.current_user = "alice"
await asyncio.sleep(0)
async def read_user():
await asyncio.sleep(0)
print(local.current_user) # "alice" from another task
async def main():
setter = asyncio.create_task(set_user())
reader = asyncio.create_task(read_user())
await setter
await reader
asyncio.run(main())The value set in set_user() is visible to the read_user() task even though read_user() was created before set_user() ran. ContextVar fixes this because each asyncio.Task receives a copy of the context at creation time.
How Contexts Are Copied and Propagated
When you create a task with asyncio.create_task(), the current context is copied into the new task. The child task sees the values set before the task was created, but changes it makes do not propagate back to the parent.
import asyncio
import contextvars
var = contextvars.ContextVar("var", default="default")
async def child():
var.set("child-value")
print("child:", var.get())
async def parent():
var.set("parent-value")
task = asyncio.create_task(child())
await task
print("parent:", var.get()) # still "parent-value"
asyncio.run(parent())This copy-on-task-creation behavior is what makes contextvars safe for async code. It also works in threaded code: each thread gets its own context, so values do not leak between threads. The same isolation that protects tasks also protects threads.
Overhead and Runtime Behavior
Both ContextVar.get() and attribute access on a threading.local object require a lookup in their respective storage; in most request handlers the cost is negligible. The more significant cost is context copying: every asyncio.create_task() copies the current context. The copy is shallow, but it is not without cost if a context holds many variables. Keep stored values focused on small request state—request IDs, user objects, transaction handles—rather than bulk data.
Another runtime detail worth knowing: ContextVar.set() returns a token. Calling token.reset() restores the previous value. This is useful when you need to scope a value to a block and guarantee cleanup even if an exception occurs.
import contextvars
var = contextvars.ContextVar("var", default="default")
token = var.set("temporary")
try:
print(var.get())
finally:
var.reset(token)
print(var.get()) # "default"Choosing Between threading.local and contextvars
Use threading.local when the code is strictly synchronous and thread-based, and there is no chance of asyncio being introduced later. It is the older, more established API and has no context-copying cost.
Use contextvars when:
- The code runs under asyncio
- The same state must be visible across async task boundaries
- You need the state to follow the logical request, not the physical thread
- You are writing a library that may be used in either threaded or async programs
contextvars is the safer default for new code because it behaves correctly in both models. threading.local is only correct when you can guarantee a thread-per-request execution model.
Compatibility and Migration Notes
contextvars works in threaded code without any special setup. Each thread has an independent context, so code written against ContextVar remains correct if you later switch the server from threads to asyncio. The standard library relies on this behavior in several places; asyncio.Task, for example, uses contextvars to create the per-task context copy described above.
Migration from threading.local to contextvars is mostly mechanical: replace attribute assignment with var.set() and attribute reads with var.get(). The one behavioral difference to watch is propagation. threading.local values are visible to any code on the same thread; ContextVar values are visible only within the same context and its child tasks. Code that relied on every task running on the same thread seeing the same value will need a different design, because contextvars isolates values by context rather than by thread.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.