Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 40 ยท Tasks and Gathering

TaskGroup and Structured Concurrency

Learn asyncio.TaskGroup for safe structured concurrency: automatic waiting, cancel-on-failure, ExceptionGroup, except* handling and when to prefer it over gather.

Starting tasks is easy. Starting them safely is harder: who waits for them? What if one fails, should the others carry on? What if the parent is cancelled? asyncio.TaskGroup (Python 3.11+) answers all of these with one rule, called structured concurrency: tasks started inside a block must finish before the block ends.

The basic shape

TaskGroup is an async context manager. Use tg.create_task(coro) to start tasks. When the async with block ends, it waits for every task automatically:

Python A TaskGroup waits for its tasks

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 line after the block runs only once every task finished, so calling .result() is safe. There is no way to "forget" a task or lose its reference, because the group holds them.

flowchart TD
    B["async with TaskGroup()"] --> T1["task 1"]
    B --> T2["task 2"]
    B --> T3["task 3"]
    T1 --> E["block exits only when<br/>all tasks are finished"]
    T2 --> E
    T3 --> E

Every task has a clear parent that waits for it. Nothing runs "loose" in the background.

When one task fails: cancel the rest

This is the biggest difference from gather. If any task in the group raises an exception, the group cancels all the other tasks, waits for them to stop, and then raises the error(s). No orphan work is left behind:

Python A failure cancels the siblings

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.

Both slow tasks were cancelled the moment failing() raised. Compare this with gather, where the siblings would keep running.

ExceptionGroup and except*

Several tasks can fail at the same time, so a TaskGroup raises an ExceptionGroup, a single exception that carries a list of others. Python 3.11 added the except* syntax to handle them by type. Each except* clause receives a group containing only the matching exceptions:

Python Handling several failures with except*

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.

All three tasks fail in the same loop turn, so all three exceptions are collected, and each except* clause receives only the ones of its type. (A task that had not failed yet would have been cancelled instead, and would not appear.) Two things to remember about except*:

  • It always receives a group, even if only one exception matched. Use eg.exceptions to look inside.
  • A regular except ValueError will not catch an ExceptionGroup. Use except*, or catch ExceptionGroup itself.

Collecting results

tg.create_task returns an ordinary Task, so keep the tasks you need and read .result() after the block ends (all are done by then):

Python Results from a TaskGroup

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.

Structured concurrency in one sentence

A function that starts concurrent work must not return until that work is finished.

That guarantee makes programs far easier to reason about: no hidden background tasks, no lost errors, no leaked resources. Callers can trust that when await process() returns, everything process started is done. TaskGroups also cooperate with cancellation and with asyncio.timeout: if the parent is cancelled, all children are cancelled too.

TaskGroup or gather?

TaskGroup gather
Failure cancels the others, raises ExceptionGroup raises first error, others keep running
Best-effort mode not built in (catch inside each task) return_exceptions=True
Tasks added dynamically yes, tg.create_task any time inside the block fixed list up front
Reference safety automatic you manage tasks

Use TaskGroup by default for all-or-nothing work. Use gather with return_exceptions=True when you want every result regardless of failures. To get best-effort behavior from a TaskGroup, catch exceptions inside each task so they never escape.

If you need to support Python versions before 3.11, the anyio library provides a nearly identical task group API.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when the async with TaskGroup block reaches its end?

    The group guarantees that all its tasks are done when the block exits.
  2. 2. One task in a TaskGroup raises. What happens to the other tasks?

    The group cancels the remaining tasks, waits for them, and then raises the collected errors.
  3. 3. Which syntax catches an ExceptionGroup containing ValueError?

    except* matches by type inside the group. A plain except ValueError does not match an ExceptionGroup.
  4. 4. Which is a good reason to choose gather(return_exceptions=True) over TaskGroup?

    gather with return_exceptions collects all outcomes, which suits best-effort batch processing.

Summary

  • async with asyncio.TaskGroup() as tg: plus tg.create_task() runs tasks concurrently and waits for all of them.
  • A failure cancels the siblings; the group then raises an ExceptionGroup, handled with except*.
  • Structured concurrency means no task outlives the block that started it.
  • Prefer TaskGroup for all-or-nothing work and gather with return_exceptions=True for best-effort batches.

Next: wait and as_completed