1. Home
  2. Blog
  3. Software Development

Software Development

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.

9 min read
Python threading explained: threads, locks, queues and the GIL, timed

Key takeaways

  • 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

Work with Stack Quora

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.

Keep reading

More guides on testing, AI & modern development

Enjoyed this article? Pick a topic and jump straight into our newest tutorials.

Artificial Intelligence

Logistic Regression in Python: Sigmoid, Log Loss and Gradient Descent From Scratch

Logistic regression in Python from scratch: sigmoid, log loss, gradient descent, odds ratios, thresholds, sigmoid overflow and separable data, tested…

Read article →
Software Development

Content Security Policy Explained: Nonces, strict-dynamic and Report-Only

Content security policy explained: nonces, strict-dynamic, Report-Only, eval, image and style rules, tested in a real browser, plus a strict…

Read article →
DevOps

Git Worktree Explained: Work on Two Branches at Once

Git worktree explained: add, list, remove, prune, lock and detached worktrees, a hotfix workflow, and the errors you will hit,…

Read article →
Test Automation

Pytest ini Explained: addopts, markers, testpaths and Precedence

Pytest ini explained: testpaths, addopts, strict markers, xfail_strict, filterwarnings, minversion, config file precedence and command-line overrides, tested.

Read article →
Software Testing

Test Estimation Techniques: WBS, Three Point PERT and Monte Carlo

Test estimation techniques worked through: WBS, three point PERT, total uncertainty, a Monte Carlo check, percentage rules and Wideband Delphi.

Read article →
Databases & SQL

Gaps and Islands in SQL: Find Streaks and Missing Ranges

Gaps and islands in SQL: find login streaks and missing ranges with ROW_NUMBER, DENSE_RANK, LAG and LEAD, plus the duplicate…

Read article →
Databases & SQL

INSERT INTO SELECT in SQL: Copy Rows Between Tables Safely

INSERT INTO SELECT in SQL: copy rows between tables with chosen columns, joins and summaries, avoid duplicates on reruns, upsert,…

Read article →
Software Development

JavaScript Proxy Explained: All 13 Traps, Reflect and Real Use Cases

JavaScript Proxy explained: all 13 traps, Reflect, validation, defaults, hidden keys, revocable proxies, private field problems and the speed cost,…

Read article →
Software Development

Python Threading Explained: Threads, Locks, Queues and the GIL, Timed

Python threading explained and timed: threads vs processes, the GIL, a real race condition, locks, ThreadPoolExecutor, queues, events and daemon…

Read article →
Software Development

Python Match Case: 12 Pattern Matching Examples, Guards and Traps

Python match case explained with 12 tested examples: literals, OR patterns, guards, sequences, dictionaries, classes, the capture trap and speed…

Read article →
Artificial Intelligence

Linear Regression in Python: Least Squares From Scratch, With R Squared

Linear regression in Python from scratch: closed form, NumPy least squares and gradient descent, R squared, RMSE, outliers and curved…

Read article →
Software Development

301 vs 302 Redirect: Differences, SEO Impact, 307 and 308

301 vs 302 redirect: the differences, SEO impact, 307 and 308, method changes, redirect chains and loops, all tested on…

Read article →
DevOps

Git Remote Explained: Add, Set-URL, Rename, Remove and Push URLs

Git remote explained: add, set-url, separate push URLs, rename, remove and prune, plus how to avoid leaking tokens in remote…

Read article →
Test Automation

Pytest Mock: mocker.patch, spy, side_effect and autospec Explained

Pytest mock explained: mocker.patch, return_value, side_effect, spy, autospec and PropertyMock, with tested examples for APIs, clocks and retries.

Read article →
Software Testing

System Testing Explained: Types, Process and a Real End-to-End Example

System testing explained: types, entry and exit criteria, the process, and a real end-to-end test suite run against a small…

Read article →
Databases & SQL

SQL Random Rows: How to Select Random Rows Fast and Fairly

SQL random rows: how to select random rows fast and fairly, timing ORDER BY RANDOM, offsets and ID jumps, and…

Read article →
Databases & SQL

SQL Median: 4 Ways to Calculate the Median, With Tested Queries

SQL median explained: four tested ways to calculate the median, including percentile functions, window ranks, offsets and per group medians.

Read article →
Software Development

JavaScript Regex Explained: Patterns, Flags, Groups and Pitfalls

JavaScript regex explained: literals, flags, groups, named groups, lookarounds, matchAll, replace and the catastrophic backtracking trap, tested in Node.

Read article →
Artificial Intelligence

Naive Bayes Classifier Explained: Build a Spam Filter in Python

Naive Bayes classifier explained by building a spam filter in Python: Bayes rule, the naive assumption, Laplace smoothing, log probabilities…

Read article →
DevOps

Git Branch Explained: Create, Switch, Rename, Delete and Recover

Git branch explained with tested commands: list, create, switch, rename, delete, merged checks, recovering deleted branches, remote tracking and naming.

Read article →
Test Automation

Pytest raises: Testing Exceptions, match and excinfo

Pytest raises explained with tested examples: match regexes, excinfo, custom and chained exceptions, parametrized error cases, pytest.warns and common mistakes.

Read article →
Software Testing

Non Functional Testing: Types, Metrics and a Real Load Test

Non functional testing explained: 10 key types, measurable requirements, latency percentiles and what a small real load test revealed about…

Read article →
Databases & SQL

SQL ROUND Function: Decimals, Ties, CEIL, FLOOR and Money

SQL ROUND explained with tested queries: decimals, tie rules, the 2.675 float trap, negative digits, CEIL, FLOOR, truncation and rounding…

Read article →
Databases & SQL

Recursive CTE in SQL: Hierarchies, Paths, Series and Cycles

Recursive CTE in SQL explained with tested queries: org charts with levels and paths, walking up a tree, team sizes,…

Read article →
Artificial Intelligence

K Means Clustering Explained: How It Works, With Python Code

K means clustering explained: the algorithm, a from-scratch NumPy version, choosing k with the elbow and silhouette methods, k-means++, scaling…

Read article →
DevOps

Git Log Explained: 15 Useful Commands and Pretty Formats

Git log explained with 15 tested commands: oneline, graph, filters by author, date, message and code, file history, stats, pretty…

Read article →
Test Automation

Pytest conftest.py Explained: Shared Fixtures, Hooks and Overrides

Pytest conftest.py explained with a tested suite: shared fixtures, scope and teardown, folder overrides, autouse, custom options, markers and useful…

Read article →
Software Testing

Usability Testing: Methods, Metrics, SUS Score and Checklist

Usability testing explained: methods, planning, writing tasks, running sessions, metrics, SUS scoring, how many users you need and a practical…

Read article →
Artificial Intelligence

K Nearest Neighbors (KNN) Explained: How It Works, With Python Code

K nearest neighbors explained: the KNN algorithm, a from-scratch NumPy version, choosing k, feature scaling, distance metrics, regression and vector…

Read article →
DevOps

Git Rebase Interactive: Squash, Fixup, Reword and Autosquash

Git rebase interactive explained step by step: pick, reword, squash, fixup, edit, drop, autosquash, conflicts and undoing a rebase with…

Read article →
Software Testing

Alpha vs Beta Testing: Key Differences, Exit Criteria and Checklist

Alpha vs beta testing compared: who tests, what each phase finds, entry and exit criteria, how to run a beta,…

Read article →
Test Automation

Pytest Monkeypatch: 10 Tested Examples for Env Vars, Time and APIs

Pytest monkeypatch explained with 10 passing tests: environment variables, functions, config, time, sleeps, paths, blocking the network and the wrong-target…

Read article →
Artificial Intelligence

Softmax Function Explained: Formula, Python Code and Stable Version

The softmax function explained: formula, worked example, NumPy code, the stable version that avoids NaN, temperature, cross-entropy and softmax vs…

Read article →
DevOps

Git Diff Explained: Staged Changes, Branches and Commits

Git diff explained: read the output, compare unstaged and staged changes, commits and branches, two dots vs three dots, and…

Read article →
Test Automation

Pytest Xdist: Run Tests in Parallel and Cut Test Time

Run pytest tests in parallel with pytest-xdist: install, the -n option, distribution modes, real timings and how to fix shared-state…

Read article →
Software Testing

Verification vs Validation in Software Testing: Example and Table

Verification vs validation in software testing explained with a comparison table and a tested coupon example where every spec test…

Read article →