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

Confusion Matrix Explained: Precision, Recall, F1 and Thresholds in Python

Confusion matrix explained with Python: TP, FP, FN, TN, precision, recall, F1, the accuracy trap, threshold choice by cost and…

Read article →
Software Development

API Pagination: Offset vs Cursor vs Keyset, Tested on 1 Million Rows

API pagination explained: offset vs keyset and cursor pagination timed on 1 million rows, duplicates when data changes, the ties…

Read article →
DevOps

Git Submodule Explained: Add, Clone, Update and Remove Safely

Git submodule explained: add, clone, update –init, update –remote, the detached HEAD trap, foreach and clean removal, tested step by…

Read article →
Test Automation

Pytest tmp path Explained: tmp_path, tmp_path_factory and Temp Files

Pytest tmp_path explained: per-test temporary folders, tmp_path_factory for shared files, monkeypatch.chdir, legacy tmpdir, retention and basetemp.

Read article →
Software Testing

Test Case Prioritization: 6 Techniques Compared With APFD

Test case prioritization compared: risk, coverage, cost, history and random orders scored with APFD and time to find all faults…

Read article →
Databases & SQL

Full Text Search in SQL: FTS5, Ranking, Phrases and Speed

Full text search in SQL with SQLite FTS5: MATCH queries, phrases, prefixes, NEAR, stemming, BM25 ranking, snippets, two gotchas and…

Read article →
Databases & SQL

Generated Columns in SQL: Virtual vs Stored, Indexes and Limits

Generated columns in SQL explained: virtual vs stored, automatic updates, write errors, storage cost, indexing, JSON fields and support in…

Read article →
Software Development

Object Freeze in JavaScript: Shallow vs Deep, Seal and const

Object freeze in JavaScript explained: freeze vs seal vs const, strict mode errors, shallow vs deep freeze, frozen arrays, Map…

Read article →
Software Development

Python hashlib: SHA-256, File Hashes, HMAC and Password Hashing

Python hashlib explained: SHA-256 for strings and files, algorithm speeds, why passwords need PBKDF2 or scrypt, safe verification and HMAC…

Read article →
Software Development

Python UUID Explained: uuid1, uuid4, uuid5, uuid7 and Database Keys

Python UUID explained: uuid4, uuid5, uuid1 privacy, time-ordered uuid7, parsing, storage formats and UUIDs as database keys, tested on Python…

Read article →
Artificial Intelligence

Random Forest in Python: Bagging, Feature Sampling and OOB From Scratch

Random forest in Python from scratch: bootstrap sampling, feature sampling, number of trees, out-of-bag evaluation and impurity vs permutation importance.

Read article →
Software Development

MIME Types Explained: Content-Type, nosniff and a Common Types List

MIME types explained and tested in a browser: Content-Type, nosniff, scripts and stylesheets with wrong types, a common MIME types…

Read article →
DevOps

Git Clean Explained: Remove Untracked Files Without Regret

Git clean explained with dry runs: -n, -f, -d, -x, -X, exclusions, paths, nested repositories and interactive mode, plus a…

Read article →
Test Automation

Pytest approx: Comparing Floats With rel, abs and Collections

Pytest approx explained: default tolerances, the near-zero trap, rel and abs, lists and dicts, NaN, NumPy, and how it differs…

Read article →
Software Testing

Accessibility Testing: WCAG Checklist, Automated Tools and Manual Checks

Accessibility testing explained: WCAG basics, an axe-core scan of a broken and a fixed page, what automation missed, contrast checks…

Read article →
Databases & SQL

SQL UNPIVOT: Turn Columns Into Rows, 4 Ways Tested

SQL UNPIVOT explained: turn columns into rows with UNION ALL, CROSS JOIN with CASE, JSON functions or native UNPIVOT, with…

Read article →
Software Development

Intl NumberFormat in JavaScript: Currency, Compact, Percent and Units

Intl.NumberFormat in JavaScript: locales, currency, compact notation, percent, units, rounding, formatToParts, the non-breaking space trap and formatter reuse.

Read article →
Databases & SQL

SQL EXPLAIN Plan: How to Read Query Plans and Fix Slow Queries

SQL EXPLAIN plan explained: read scans, index searches, covering indexes and temporary sorts, with before and after timings for five…

Read article →
Artificial Intelligence

Decision Tree in Python: Gini, Entropy and Overfitting From Scratch

Decision tree in Python from scratch: Gini impurity, entropy, information gain, best splits, readable rules, and how depth and leaf…

Read article →
DevOps

Git Blame Explained: Find Who Changed a Line, and Why

Git blame explained with a real repository: ignore whitespace, line ranges and functions, ignore-revs files for formatting commits, moved code…

Read article →
Test Automation

Pytest Benchmark: Measure Speed and Catch Performance Regressions

Pytest benchmark tutorial: the benchmark fixture, reading results, parametrized and pedantic benchmarks, saving baselines and failing the build on regressions.

Read article →
Software Testing

Defect Density: Formula, Worked Examples and How to Use It

Defect density explained: the formula, a five-module worked example, per KLOC vs per function point, severity weighting, defect removal efficiency…

Read article →
Databases & SQL

Case Insensitive Search in SQL: LOWER, LIKE, COLLATE and Indexes

Case insensitive search in SQL: LOWER, LIKE, COLLATE NOCASE and expression indexes compared with query plans, plus accented letters and…

Read article →
Databases & SQL

ON DELETE CASCADE in SQL: CASCADE vs SET NULL vs RESTRICT

ON DELETE CASCADE in SQL tested: CASCADE vs SET NULL vs RESTRICT, multi-level cascades, the SQLite foreign key pragma, row…

Read article →
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 →
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 →
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 →
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 →
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 →