Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The concurrent.futures module

Reference for Python's concurrent.futures: ThreadPoolExecutor, ProcessPoolExecutor, submit, map, Future, as_completed, wait, timeouts and exceptions.

The concurrent.futures module is the simplest way to run work in the background. You create an executor (a pool of worker threads or processes), hand it functions to run, and get back Future objects: placeholders for results that will exist later. The pool takes care of starting and reusing workers, queuing tasks, passing results and carrying exceptions back to you.

Use ThreadPoolExecutor for I/O-bound tasks such as downloading many URLs or reading many files, and ProcessPoolExecutor for CPU-bound work that needs more than one core. Both have the same interface, so you can switch between them by changing one name.

Python
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(len, ["a", "bb", "ccc"]))
# [1, 2, 3]

The in-browser runner cannot start threads or processes, so real pools raise an error here. The examples below use Future objects directly and a small single-threaded executor built on the same Executor base class; the ThreadPoolExecutor code is shown read-only.

Try it

Python Future objects, as_completed and wait

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.

Python A serial executor with the real Executor API

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 same code with a real thread pool (read-only; run it in a normal Python environment):

Python
from concurrent.futures import ThreadPoolExecutor, as_completed

def parse(text):
    return int(text) * 10

with ThreadPoolExecutor(max_workers=3) as pool:
    futures = {pool.submit(parse, t): t for t in ["1", "2", "x", "4"]}
    for fut in as_completed(futures):       # in completion order, not submission order
        try:
            print(futures[fut], "->", fut.result())
        except ValueError as e:
            print(futures[fut], "failed:", e)

Syntax

Python
ThreadPoolExecutor(max_workers=None, thread_name_prefix="", initializer=None, initargs=())
ProcessPoolExecutor(max_workers=None, mp_context=None, initializer=None, initargs=(), max_tasks_per_child=None)
Member Description
submit(fn, /, *args, **kwargs) Schedules fn(*args, **kwargs) and returns a Future immediately.
map(fn, *iterables, timeout=None, chunksize=1) Like built-in map(), but the calls run concurrently. Yields results in input order; an exception appears when you reach that item. (chunksize is used only by process pools.)
shutdown(wait=True, *, cancel_futures=False) Stops accepting work and optionally waits for running tasks. with calls it for you.
Future.result(timeout=None) Waits for and returns the result, or re-raises the task's exception.
Future.exception(timeout=None) Returns the task's exception, or None.
Future.done(), running(), cancelled() Status checks.
Future.cancel() Cancels a task that has not started; returns whether it worked.
Future.add_done_callback(fn) Calls fn(future) when the future finishes.
as_completed(futures, timeout=None) Iterator over futures as they finish.
wait(futures, timeout=None, return_when=ALL_COMPLETED) Returns (done, not_done) sets. Other options: FIRST_COMPLETED, FIRST_EXCEPTION.

Raises: concurrent.futures.TimeoutError (an alias of the built-in TimeoutError since 3.11) when a timeout expires, CancelledError when you call result() on a cancelled future, BrokenExecutor (for example BrokenProcessPool) if a worker dies, and RuntimeError when you submit after shutdown.

Usage notes

  • Always use with (or call shutdown()), otherwise the program may wait for idle workers at exit.
  • result() re-raises the task's exception in the calling code with the original traceback. If you never call result() or exception(), errors are silent.
  • map() versus submit(): map() is shortest when you want all results in order; submit() plus as_completed() gives results as soon as each is ready and lets you attach context (a dictionary from future to input).
  • Thread pools do not speed up CPU-bound Python code because of the GIL; process pools do, at the price of pickling arguments and results (see multiprocessing). Process pools also need the if __name__ == "__main__": guard on spawn-based platforms.
  • Default max_workers: for threads it is min(32, os.cpu_count() + 4) (3.8+); for processes it is the CPU count.
  • A cancelled or running task cannot be interrupted. cancel() only works on queued tasks; a running task has to finish.
  • Do not wait on futures from inside the same pool's tasks: if every worker waits for a queued task, the pool deadlocks.
  • Bridging to asyncio: loop.run_in_executor(pool, fn, *args) runs blocking calls without freezing the event loop.
  • Thread-safety is still your job. Tasks that modify shared data need locks, or better, return results and combine them in the caller.