Python Threading Explained: Threads, Locks, Queues and the GIL, Timed
Python threading runs several tasks at once inside one process. It can cut waiting time for network and file work dramatically, but it does almost nothing for CPU-heavy code because of the GIL. We timed both cases, caught a real race condition losing 68 percent of updates, and fixed it with a lock, plus queues, events and thread pools.
- Python threading made ten 0.5-second waits finish in 0.51 seconds instead of 5.0.
- For CPU-bound work, four threads took 3.85 seconds versus 4.27 sequentially; four processes took 3.01.
- Without a lock, four threads doing read-then-write on a counter produced 1,289 instead of 4,000. With a lock: 4,000.
- Prefer
ThreadPoolExecutor: it re-raises worker exceptions in your code, while a raw Thread only prints them.
Programs spend a surprising amount of time waiting: for a web API to answer, a file to download, a database to reply. While one task waits, the CPU sits idle. Python threading lets other tasks run during those waits. It is built into the standard library, needs no installation, and is often the quickest way to make a slow script several times faster.
All timings below come from Python 3.13.6 (the standard build, with the GIL enabled, as sys._is_gil_enabled() confirmed) on a 4-core Windows laptop. We simulated network calls with time.sleep, which releases the GIL exactly as real I/O does.
What is a thread?
A thread is an independent flow of execution inside a process. All threads in a process share the same memory: the same variables, objects and open files. That sharing is what makes threads lightweight and fast to start, and it is also what makes them dangerous, because two threads can change the same data at the same moment.
Starting and joining threads
import threading, time
def fake_io(i):
time.sleep(0.5) # stands in for a network call
return i * 2
threads = [threading.Thread(target=fake_io, args=(i,)) for i in range(10)]
for t in threads: t.start()
for t in threads: t.join() # wait for all of them to finish
start() launches the thread and returns immediately. join() blocks until that thread finishes. Forgetting join() is a common bug: your main code carries on and may read results that do not exist yet. Notice that a plain Thread gives you no easy way to get the return value back; that is one reason to use a pool.
The I/O speed-up, timed
| Approach | 10 tasks of 0.5 s each |
|---|---|
| Sequential loop | 5.0 s |
| 10 threads | 0.51 s |
| ThreadPoolExecutor, 5 workers | 1.0 s |
Ten threads all waited at the same time, so the total was one wait instead of ten: almost exactly ten times faster. With five workers the pool ran two rounds of five, so it took two waits. That is the trade-off: more threads mean more parallel waiting, but each thread costs memory, and the server you call may rate-limit you. For calling APIs politely, see our API rate limiting guide.
ThreadPoolExecutor: the easy way
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=5) as ex:
results = list(ex.map(fake_io, range(10)))
# [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]
concurrent.futures manages a fixed set of worker threads and a work queue for you. map returns results in input order, the with block waits for all work and shuts the pool down, and exceptions are not lost. For most real programs, this is the only threading API you need. It is a good example of the context manager pattern doing cleanup for you.
The GIL: why threads do not speed up CPU work
def cpu(n):
s = 0
for i in range(n): s += i * i
return s
# 4 x cpu(20_000_000)
# sequential 4.27s threads 3.85s processes 3.01s
CPython has a Global Interpreter Lock (GIL): only one thread executes Python bytecode at a time. Threads take turns, so pure Python calculations do not run in parallel. Four threads were about the same as running sequentially (with smaller workloads of 3 million iterations, the three repeated rounds gave 0.57 versus 0.54 seconds). Separate processes, each with its own interpreter and GIL, did run in parallel and were fastest, although process start-up overhead on Windows kept the gain to about 30 percent on this machine. With tiny workloads, processes were actually slower: 0.73 seconds versus 0.57.
The GIL is released during I/O waits, time.sleep, and inside many C extensions such as NumPy, hashlib and zlib, which is why threads work so well for network code. Python 3.13 also ships an optional free-threaded build without the GIL; we did not test it here, and the standard installer still uses the GIL.
A real race condition
counter = 0
def inc(n):
global counter
for _ in range(n):
v = counter # read
time.sleep(0) # let another thread run
counter = v + 1 # write
# 4 threads x 1,000 increments
# race result 1289 expected 4000
Each thread read the counter, yielded, then wrote back its old value plus one, overwriting updates made by other threads in between. 2,711 of 4,000 updates vanished. Real code hits the same bug whenever a thread reads shared state, does any work (a log call, an API request, even a dictionary lookup), then writes back.
Interestingly, a plain counter += 1 loop with four threads and four million increments gave the correct 4,000,000 in our run. That does not make it safe: += on a global is several bytecodes, not an atomic operation, and the GIL can switch threads between them. Recent CPython versions switch less often in such tight loops, which hides the bug in tests and lets it appear in production. Never rely on it.
Fixing it with a Lock
lock = threading.Lock()
def inc2(n):
global counter
for _ in range(n):
with lock:
v = counter
time.sleep(0)
counter = v + 1
# locked result 4000
A lock lets only one thread at a time into the critical section. The with lock: form always releases the lock, even if an exception is raised. Keep critical sections short, because every other thread waits while one holds the lock, and always acquire multiple locks in the same order to avoid deadlocks. threading.RLock is a variant the same thread may acquire repeatedly.
Exceptions inside threads
with ThreadPoolExecutor(4) as ex:
futs = {ex.submit(bad, i): i for i in range(5)}
for f in as_completed(futs):
try: f.result()
except ValueError as e: print("caught:", e)
# caught: item 3 failed
threading.Thread(target=bad, args=(3,)).start()
# Exception in thread Thread-23 (bad): ... ValueError: item 3 failed
# (printed to stderr, main thread carries on)
With a pool, future.result() re-raised the worker’s exception in the main thread, where normal exception handling applies. With a raw Thread, the traceback was printed and then ignored; the main program never knew the work failed. That silent failure is the strongest argument for pools. If you do use raw threads, wrap the target in try/except and record failures, for example with the logging module, which is thread-safe.
Producer and consumer with queue.Queue
q = queue.Queue()
def worker():
while True:
item = q.get()
if item is None: # sentinel: stop
q.task_done(); break
out.append(item * item)
q.task_done()
# 3 workers, 9 items, then one None per worker
# queue results [0, 1, 4, 9, 16, 25, 36, 49, 64]
queue.Queue is thread-safe: any number of threads can put and get without extra locks. Workers block on get() until work arrives, and a None sentinel per worker tells each to exit. q.join() waits until every item has been marked done. Use Queue(maxsize=100) to stop a fast producer from filling memory.
Stopping a thread cleanly with Event
stop = threading.Event()
def ticker():
while not stop.is_set():
ticks.append(1)
stop.wait(0.1) # sleeps, but wakes at once when set
# main: sleep 0.55 s, then stop.set()
# ticks before stop 6
Python has no safe way to kill a thread from outside. Instead, threads check a shared Event and exit on their own. Using stop.wait(0.1) rather than time.sleep(0.1) means the thread wakes up immediately when the event is set, instead of finishing its sleep.
Daemon threads
A thread created with daemon=True does not keep the program alive: when the main thread ends, daemon threads are stopped abruptly, without running cleanup code or flushing files. Use them only for background helpers whose work can be lost, such as a heartbeat or a cache refresher. Anything that writes data should be a normal thread with an Event to stop it and a join() at shutdown. At the end of our script, threading.active_count() was 1, meaning only the main thread was left.
Threads vs processes vs asyncio
| Workload | Best tool | Why |
|---|---|---|
| Many network or file waits | Threads (ThreadPoolExecutor) | GIL released during I/O, works with any library |
| Thousands of concurrent connections | asyncio | One thread, very low cost per task, needs async libraries |
| Pure Python number crunching | Processes (ProcessPoolExecutor) | Each process has its own GIL |
| NumPy or other C-heavy work | Threads can help | Many C extensions release the GIL |
Final thoughts
Python threading is the right tool when your program waits: our ten simulated requests went from 5 seconds to half a second. It is the wrong tool for pure Python calculations, where the GIL kept four threads at roughly sequential speed. Use ThreadPoolExecutor so results and exceptions come back to you, protect shared state with a lock, pass work through a Queue, and stop threads with an Event. Follow those rules and threads become a safe, simple speed-up rather than a source of strange bugs.
Frequently asked questions
Does Python threading run in parallel?
Threads run concurrently, and they truly overlap while waiting for I/O. In the standard CPython build the GIL lets only one thread run Python bytecode at a time, so CPU-bound Python code does not run in parallel.
When should I use threading instead of multiprocessing?
Use threads for work that waits on networks, disks or databases. Use multiprocessing for CPU-heavy pure Python work, since each process has its own interpreter and GIL.
Is counter += 1 thread safe in Python?
No. It is several bytecode steps, so a thread switch between the read and the write can lose updates. Protect shared counters with a threading Lock.
How do I get a return value from a thread?
Use ThreadPoolExecutor. submit returns a future, and future.result gives the return value or re-raises the exception from the worker thread.
How do I stop a thread in Python?
There is no safe way to kill one from outside. Give the thread a threading Event to check in its loop, set the event when you want it to stop, then call join.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.