Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~4 min readPython
#contextvars#threading.local#asyncio#concurrency
A split diagram contrasting thread-local storage in threads with contextvars context propagation across async tasks in Python.

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.

python
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().

python
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 context

The 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.

python
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.

python
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.

python
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 tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.