Python's threading.local: Per-Thread Data Storage
Learn how to use Python's threading.local to store per-thread data, avoid race conditions, and manage context in multithreaded applications.

Python's threading.local gives each thread its own isolated storage for attributes. When you set an attribute on a threading.local() instance, only the thread that set it can see that value; every other thread has its own separate value. This makes it useful for holding per-thread context such as request IDs, user IDs, or database connections without passing a context object through every function call.
What Problem Does threading.local Solve?
In a multithreaded program, a global variable is shared by all threads. If two threads write to it at the same time, the result can be a race condition and unpredictable behavior. The usual alternative is to pass a context object through every function call, but that becomes cumbersome when the call stack is deep or when the state is only needed in a few places.
threading.local provides a simpler model. You create one local() instance, and each thread that accesses it gets its own namespace. You can set and read attributes on that instance from any thread without affecting another thread's values. This is thread-local storage (TLS), and it is a standard way to hold per-thread state in threaded applications.
How threading.local Works
threading handles the mapping between the current thread and its own attribute dictionary, so you do not need to manage thread identifiers yourself. From your code's perspective, a shared local() object behaves as if each thread has its own private attribute dictionary. You generally do not need to lock access to per-thread attributes, because other threads cannot see that thread's values.
One important detail: the local() object itself can be shared, such as a module-level variable, but the attributes are not shared. Each thread sees only the values it has set. This is why threading.local is a common choice for module-level context in threaded applications.
Basic Usage of threading.local
Using threading.local is straightforward. Create an instance, then set attributes on it from any thread. Here is a minimal example:
import threading
local_data = threading.local()
def worker(name):
local_data.name = name
print(f'Thread {name} sees: {local_data.name}')
threads = []
for i in range(3):
t = threading.Thread(target=worker, args=(f'worker-{i}',))
threads.append(t)
t.start()
for t in threads:
t.join()Each thread sets local_data.name to its own value before reading it, so the print statement shows that thread's value. If you need an attribute that might not exist yet, initialize it lazily with hasattr() or a try/except block.
Typical Use Cases
threading.local is most useful when separate threads need independent context that is shared across many functions. Common examples include:
- Request context in web servers: store the current request object once, then let any function in the call stack read it without passing it explicitly.
- Database connections: keep one connection per worker thread so connections are reused but never shared across threads.
- Logging context: store a request ID or user ID, and have a logging filter or formatter include it in messages from the current thread.
These patterns are common in threaded server applications, where each incoming request is handled by a single worker thread.
Common Pitfalls and Mistakes
Thread-local data lasts for the life of the thread. That is convenient, but it can cause stale state in thread pools. A worker thread may handle many tasks over time; if one task sets local_data.request_id and a later task does not replace it, the later task will see the previous request's ID.
Avoid this by clearing the attributes at the start or end of each task. A try/finally block or a small context manager can guarantee cleanup:
import threading
local_data = threading.local()
def handle_task(task_id):
local_data.task_id = task_id
try:
# Do work with local_data.task_id
print(local_data.task_id)
finally:
del local_data.task_idAnother common mistake is using threading.local in asyncio code. threading.local is tied to OS threads, not to async tasks. All coroutines in an event loop run on the same thread, so they share the same threading.local attributes. If you need per-task context in async code, use contextvars instead.
Performance and Memory Considerations
Each thread that touches a threading.local object has its own attribute storage. Creating the object is cheap, and attribute access is a normal dictionary-style lookup, so the overhead is small in most applications. If you access the same attribute repeatedly in a hot loop, however, reading it into a local variable once may be faster.
Memory can also add up. If many threads each store large objects in thread-local attributes, those objects live as long as the threads do. In a thread pool, that can mean data from one task remains attached to the worker thread after the task finishes. Delete attributes or set them to None explicitly when they are no longer needed.
Alternatives: contextvars and Explicit Passing
contextvars was introduced in Python 3.7 for managing context in both synchronous and asynchronous code. Unlike threading.local, contextvars works with asyncio tasks and can propagate context across await points. If you are writing code that may need async support, contextvars is usually the better choice.
Explicitly passing a context object is still the simplest and most predictable approach when the state is only needed in a few functions. It makes dependencies visible and easy to test, though it becomes verbose in deep call stacks. The tradeoff is convenience versus explicitness.
| Approach | Best For | Async Support | Overhead |
|---|---|---|---|
threading.local | Thread-based concurrency | No | Low |
contextvars | Async and sync code | Yes | Low |
| Explicit passing | Small call stacks | Yes | None |
For asyncio applications, avoid threading.local. Because coroutines share the same OS thread, they would all see the same attributes, which can leak data between tasks. Use a contextvars.ContextVar instead and set it at the start of each task. All coroutines called within that task will see the same value, and each new task starts with its own context copy.
Production Best Practices
- Clear thread-local attributes at the end of each task, especially when using thread pools. Use
try/finallyor a context manager. - Avoid storing large objects in thread-local attributes unless necessary, and delete them promptly when they are no longer needed.
- Remember that
threading.localisolates data per thread; it does not synchronize access to shared resources. You still need locks for shared state. - Document the lifecycle of the stored data. Because the data persists for the thread's lifetime, other developers need to know when it is safe to rely on it.
- For new code, consider whether
contextvarswould better fit your current or planned concurrency model.
Use threading.local when you need simple, per-thread state in threaded code. Use contextvars when you need the same behavior in asynchronous code.
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.