Skip to content
Tutorials Center
My learning

Topics

Lesson 86 of 149 ยท Beyond the Basics

Threads, Processes and concurrent.futures

Learn when to use threads, processes or asyncio in Python. Understand the GIL, avoid race conditions with locks, and run jobs with ThreadPoolExecutor.

In Async Programming with asyncio you saw one way to juggle many jobs at once: a single thread that switches between coroutines whenever they wait. Python has two more tools for doing several things at the same time. Threads run several flows of code inside one program. Processes run several separate copies of Python, each with its own memory, so they can use every core of your processor.

This lesson explains when each tool helps and when it doesn't, what the famous GIL is, why shared data needs locks, and how the concurrent.futures module gives threads and processes one simple interface. You'll also learn how to pick between threads, processes and asyncio for a real task.

About the editors on this page. Python here runs inside your browser, which does not let it start operating-system threads or processes. So the thread and process code in this lesson is shown as read-only snippets that you can run on your own computer. The live editors use small simulations that show the same ideas.

Concurrency vs parallelism

Two words get mixed up a lot:

  • Concurrency means managing several tasks at once. They take turns, and progress on each overlaps in time. One cashier serving three queues by switching between them is concurrent.
  • Parallelism means executing several tasks at the same instant, on different processor cores. Three cashiers at three tills is parallel.

Which one you need depends on what your program spends its time doing:

Kind of work Where the time goes Examples What helps
I/O-bound Waiting for something outside the CPU Downloading pages, calling APIs, querying databases, reading files Concurrency: threads or asyncio
CPU-bound Calculating Resizing images, parsing huge files, simulations, hashing Parallelism: processes

If your program waits on the network 95% of the time, extra cores won't help, but overlapping the waits will. If your program crunches numbers non-stop, overlapping does nothing, and only more cores will make it faster.

Threads with the threading module

A thread is an independent flow of execution inside a program. Every program starts with one, the main thread. You can start more with threading.Thread:

Python
import threading
import time

def download(name: str) -> None:
    print(f"start {name}")
    time.sleep(1)                     # stands in for a slow network call
    print(f"done  {name}")

threads = [threading.Thread(target=download, args=(name,))
           for name in ["a.csv", "b.csv", "c.csv"]]

for thread in threads:
    thread.start()                    # begin running download() in the background
for thread in threads:
    thread.join()                     # wait for it to finish

print("all downloads finished")       # about 1 second in total, not 3
  • target is the function the thread runs, and args is a tuple of its arguments.
  • start() launches the thread and returns immediately. The main thread keeps going.
  • join() waits until that thread has finished. Forgetting join() means your program may move on before the work is done.

All three threads wait at the same time, so the program takes about one second instead of three. Run the next editor to see what happens when the browser refuses to start a thread:

Python The main thread, and a thread that can't start here

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The GIL, and free-threaded Python

The standard Python interpreter (CPython) has a Global Interpreter Lock, or GIL. It lets only one thread run Python code at a time. Threads still take turns rapidly, and a thread that is waiting for I/O (a socket, a file, time.sleep()) releases the GIL so others can run.

That gives a simple rule of thumb for regular CPython:

  • Threads do speed up I/O-bound work, because the waiting overlaps.
  • Threads don't speed up CPU-bound pure-Python work, because only one thread computes at any moment. Two threads summing numbers take about as long as one, sometimes longer.

Libraries written in C, such as NumPy, hashlib and zlib, often release the GIL during long operations, so threads can help there too.

The GIL is slowly becoming optional. Python 3.13 introduced an experimental free-threaded build without a GIL, and since Python 3.14 that build is officially supported (it is a separate download, often run as python3.14t). The normal build still has the GIL, and some third-party packages don't yet support the free-threaded one, so for now, plan your code around the GIL.

Race conditions and locks

Threads share the program's memory. That's convenient, but dangerous: if two threads update the same value, their steps can interleave in a way that loses data. This bug is called a race condition.

Even balance += 1 is not one step. It is read the value, add one, write it back. If a thread is paused between reading and writing, another thread's update gets overwritten.

The simulation below models two threads as generators. Each yield is a point where the "scheduler" switches to the other worker:

Python Simulating a race condition

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Half of the deposits vanished: both workers read the same old balance, and the second write overwrote the first. Real threads switch at unpredictable moments, so the real bug is worse: it shows up only sometimes, which makes it very hard to track down.

The fix is a threading.Lock. Only one thread can hold a lock at a time, and the others wait at the with statement until it is free:

Python
import threading

balance = 0
balance_lock = threading.Lock()

def deposit(amount: int, times: int) -> None:
    global balance
    for _ in range(times):
        with balance_lock:            # acquire, run the block, always release
            balance += amount

Use the lock as a context manager so it is released even if the block raises an exception. Keep locked sections short, and avoid holding two locks at once where you can: two threads that each hold one lock and wait for the other's will wait forever. That is a deadlock.

Share less, and you need fewer locks. The safest threaded code doesn't share mutable data at all. Give each thread its own input, and collect results with queue.Queue or concurrent.futures, which handle the locking for you.

concurrent.futures: pools of workers

Starting and joining threads by hand gets tedious. The concurrent.futures module offers executors: a pool of workers that you hand jobs to. You get a future back for each job, an object that will hold the result (or the exception) once the job finishes.

Python
from concurrent.futures import ThreadPoolExecutor, as_completed
import urllib.request

urls = ["https://example.com", "https://example.org", "https://example.net"]

def page_size(url: str) -> int:
    with urllib.request.urlopen(url, timeout=10) as response:
        return len(response.read())

with ThreadPoolExecutor(max_workers=8) as pool:
    # Option 1: map() returns results in the same order as the inputs.
    for url, size in zip(urls, pool.map(page_size, urls)):
        print(url, size)

    # Option 2: submit() each job, then handle results as they finish.
    futures = {pool.submit(page_size, url): url for url in urls}
    for future in as_completed(futures):
        print(futures[future], future.result())

The with block waits for every job before it ends, so you never forget a join(). future.result() returns the job's value, or re-raises the exception the job raised.

Because executors share one interface, you can try it out here with a tiny executor of our own that runs each job immediately instead of in a thread. The calling code is exactly what you'd write with a ThreadPoolExecutor:

Python The executor and future interface

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice how a failing job doesn't crash the others. Its exception waits inside the future until you call result(). And as_completed() gives you futures in the order they finish, which with real threads is rarely the order you submitted them.

How much faster is a pool?

For I/O-bound jobs, a pool of n workers can come close to an n-times speed-up. This simulation schedules eight "downloads" on one worker and then on four, always handing the next job to whichever worker is free first:

Python Simulating a worker pool

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Six and a half seconds become just over two. Change workers to 8 or 2 and watch the total move. In real programs the gain levels off: servers limit connections, and each thread costs some memory, so pools of 4 to 32 threads are typical for I/O work.

Processes for CPU-bound work

To make CPU-heavy Python code faster, use several processes. Each process is a separate Python interpreter with its own memory and its own GIL, so they really do run in parallel on different cores. ProcessPoolExecutor has the same interface you just used:

Python
from concurrent.futures import ProcessPoolExecutor
import math

def count_primes(limit: int) -> int:
    return sum(1 for n in range(2, limit)
               if all(n % d for d in range(2, math.isqrt(n) + 1)))

if __name__ == "__main__":                       # required for process pools
    limits = [200_000, 210_000, 220_000, 230_000]
    with ProcessPoolExecutor() as pool:          # one worker per CPU core by default
        for limit, primes in zip(limits, pool.map(count_primes, limits)):
            print(f"{primes} primes below {limit}")

Processes come with rules that threads don't have:

  • Guard the entry point with if __name__ == "__main__":. On Windows and macOS, each worker process imports your main file. Without the guard, every worker would start a pool of its own.
  • Everything sent between processes is pickled. Arguments and return values travel as bytes, so they must be picklable, and the functions must be defined at the top level of a module (not lambdas or nested functions). Large data costs time to copy.
  • No shared variables. A global changed in a worker is changed only in that worker's copy of memory. Return results instead.
  • Startup costs. Launching a process takes far longer than starting a thread, so give each one a decent chunk of work.

The lower-level multiprocessing module offers Process, Pool, Queue and shared-memory tools for cases the executor doesn't cover. Python 3.14 also added InterpreterPoolExecutor, which runs jobs in separate interpreters inside one process, a middle ground that is still new and best treated as experimental for now.

multiprocessing.Pool and parallel map

ProcessPoolExecutor covers most needs, but you will meet its older sibling, multiprocessing.Pool, in plenty of existing code. A pool starts a fixed number of worker processes once and then feeds them tasks, so you pay the startup cost a single time. Its methods:

Method Returns Use it for
pool.map(f, items) a list, in input order one argument per call, waits for everything
pool.starmap(f, tuples) a list, in input order several arguments per call: f(*args) for each tuple
pool.imap(f, items) an iterator, in input order results as they become available, in order
pool.imap_unordered(f, items) an iterator, fastest first handling results as soon as they finish
pool.apply_async(f, args) an AsyncResult one job at a time, with callback= and .get(timeout)
Python
from multiprocessing import Pool, cpu_count
import hashlib

def checksum(path: str) -> tuple[str, str]:
    with open(path, "rb") as handle:
        return path, hashlib.sha256(handle.read()).hexdigest()[:12]

def power(base: int, exponent: int) -> int:
    return base ** exponent

if __name__ == "__main__":                       # required on Windows and macOS
    files = ["a.bin", "b.bin", "c.bin", "d.bin"]
    with Pool(processes=cpu_count()) as pool:
        for path, digest in pool.imap_unordered(checksum, files):
            print(path, digest)                  # printed in finishing order

        print(pool.starmap(power, [(2, 10), (3, 4), (10, 3)]))   # [1024, 81, 1000]

        job = pool.apply_async(power, (7, 7))
        print(job.get(timeout=5))                # 823543; raises TimeoutError if too slow

With Pool as a context manager, leaving the with block calls terminate(), which stops workers even if jobs are still running. That is fine after map() (it already waited), but if you started apply_async() jobs, call get() on every result before you leave the block, or call pool.close() and pool.join() instead of relying on the with statement.

Chunks: why chunksize matters

Sending one tiny task at a time across a process boundary is slow, because every task is pickled, sent through a pipe and unpickled. To cut the overhead, map() splits the input into chunks and ships a whole chunk per message. You can set the size with chunksize=; if you don't, Python picks one based on the input length and the number of workers. Many tiny tasks favor a large chunk. A few slow tasks of uneven length favor chunksize=1, so that no worker sits idle while another holds a long queue.

The simulation below can't start processes in the browser, but it shows the arithmetic of chunking and why an uneven workload prefers small chunks:

Python Chunking work across workers (simulation)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With chunksize=15, one worker gets everything, so three workers take as long as one. With small chunks, the slow jobs spread out and the quick ones fill the gaps. (Real chunking also costs a little time per message, which is why you shouldn't always choose 1: for a million tiny tasks, a larger chunk is far faster.)

What can be sent to a worker

Everything crossing the process boundary is pickled, and pickling has limits. You can check a function or an argument yourself before handing it to a pool:

Python What can be pickled?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Lambdas, nested functions, generators, locks and open files can't be pickled, so they can't be passed to or returned from a pool worker. Define worker functions at the top level of a module, pass file names instead of open files, and return finished values instead of generators.

Passing data between processes

Because memory isn't shared, processes that need to talk use explicit channels from multiprocessing:

  • Queue is a process-safe FIFO for passing objects. It is the standard way to build a producer/consumer pipeline.
  • Pipe() gives two connected endpoints, good for a conversation between exactly two processes.
  • Value and Array place a single number or a fixed array in shared memory, protected by a lock.
  • shared_memory.SharedMemory gives a named block of raw memory that several processes can map without copying. Combined with NumPy, it avoids copying huge arrays.
  • Manager() runs a server process that hosts shared lists and dicts, which you use through proxies. It is convenient but slower, since every access is a message.
Python
from multiprocessing import Process, Queue, Value

def producer(queue: Queue, count: int) -> None:
    for n in range(count):
        queue.put(n * n)
    queue.put(None)                               # sentinel: "no more work"

def consumer(queue: Queue, total) -> None:
    while (item := queue.get()) is not None:
        with total.get_lock():                    # the Value's built-in lock
            total.value += item

if __name__ == "__main__":
    queue = Queue()
    total = Value("i", 0)                          # a shared C int, starts at 0
    workers = [Process(target=producer, args=(queue, 10)),
               Process(target=consumer, args=(queue, total))]
    for worker in workers:
        worker.start()
    for worker in workers:
        worker.join()
    print(total.value)                             # 285 = 0 + 1 + 4 + ... + 81

Two habits keep this pattern healthy. First, send a sentinel such as None so the consumer knows when to stop, instead of guessing from a timeout. Second, remember that total.value += item is a read, an add and a write, exactly the race you saw in the threads section, so hold get_lock() around it. The simulation below runs the queue-and-sentinel idea in one process, with generators standing in for the two processes:

Python A producer/consumer pipeline with a sentinel (simulation)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The consumer starts first, finds the queue empty and says "waiting", then consumes items as the producer supplies them and stops cleanly at the sentinel. Real multiprocessing.Queue objects behave the same way, with the difference that each side runs in its own process.

Prefer the simplest tool that fits. Reach for ProcessPoolExecutor or Pool.map when each job is independent. Use a queue when work arrives over time. Shared memory is an optimization for very large arrays, and a Manager is for the occasional shared dictionary; neither is the first thing to try.

Choosing the right tool

Situation Best fit
Many network calls, and an async library exists (httpx, aiohttp) asyncio
Some network or file calls with ordinary blocking libraries (requests, urllib) ThreadPoolExecutor
Heavy computation in pure Python ProcessPoolExecutor
Heavy number crunching on arrays Vectorized NumPy first, then processes if still slow
A short script that does one thing at a time No concurrency at all

Concurrency makes code harder to read, test and debug. Measure first (see Measuring and Improving Performance), and add it only where the waiting or computing actually hurts.

Check your understanding

Quick check ยท 8 questions

of 8 answered You scored / 8 ยท perfect!

  1. 1. Your script downloads 200 web pages one after another and is slow. In standard CPython, what is the simplest effective fix?

    Downloads are I/O-bound. Threads release the GIL while waiting, so a thread pool overlaps the waits. Processes would work too but cost much more to start.
  2. 2. What does the GIL prevent in the standard CPython build?

    The Global Interpreter Lock lets only one thread execute Python code at a time. Separate processes each have their own GIL, and threads can still overlap while waiting on I/O.
  3. 3. Why can counter += 1 lose updates when several threads run it?

    If a thread is paused after reading but before writing, another thread's update is overwritten. Protect the update with a threading.Lock.
  4. 4. Why must process-pool code sit under if __name__ == "__main__":?

    On Windows and macOS, workers start by importing your main file. The guard keeps the pool-creating code from running again inside every worker.
  5. 5. What does future.result() do if the job raised an exception?

    The exception is stored in the future and raised again when you ask for the result, so you can handle it with an ordinary try/except.
  6. 6. Which Pool method returns results in the order they finish rather than the input order?

    imap_unordered yields each result as soon as a worker finishes it. map, starmap and imap keep the input order.
  7. 7. Why does Pool.map(lambda n: n * 2, numbers) fail?

    Arguments and functions travel between processes as pickled bytes, and a lambda has no importable name. Define the function at the top level of a module.
  8. 8. When is a small chunksize (even 1) the better choice for Pool.map?

    Small chunks balance an uneven workload across workers. Large chunks cut messaging overhead for many tiny tasks.

Summary

  • I/O-bound work spends its time waiting and benefits from concurrency; CPU-bound work needs parallelism on several cores.

  • threading.Thread runs a function in the background; start() launches it and join() waits for it.

  • In standard CPython, the GIL lets one thread run Python code at a time, so threads help I/O but not pure-Python computation. A free-threaded build without the GIL is officially supported since 3.14 but is not the default.

  • Shared mutable data causes race conditions; protect it with threading.Lock, or better, avoid sharing.

  • ThreadPoolExecutor and ProcessPoolExecutor share one interface: map(), submit(), futures and as_completed().

  • multiprocessing.Pool offers map, starmap, imap, imap_unordered and apply_async; chunksize trades messaging overhead against load balance.

  • Only picklable objects cross process boundaries: no lambdas, nested functions, generators, locks or open files.

  • Processes share data through Queue (with a sentinel), Pipe, Value/Array (hold get_lock()), shared memory or a Manager.

  • Processes need the __main__ guard, picklable arguments and enough work per job to pay for their startup.

Next: Testing with unittest and doctest, where you'll make Python check your code for you.