Learning Tips | Published Nov 17, 2026 | 8 min read

Python asyncio.TaskGroup: A Practical Guide

Learn Python 3.11 TaskGroup patterns for concurrent coroutines, sibling cancellation, exception groups, timeouts, and cleanup.

Diagram showing a parent coroutine owning two asyncio TaskGroup child tasks, waiting on success and cancelling unfinished siblings after failure

Python asyncio.TaskGroup provides a structured way to start related coroutines, wait for them together, and clean up sibling work when a task fails. Added in Python 3.11, it is useful when a request needs several independent results but should not leave background tasks running after an error.

Why group related tasks?

Calling an async function creates a coroutine object; it does not by itself run the work concurrently. You can schedule coroutines as tasks and await them, but manually tracking tasks and remembering to cancel or join them on every exit path is easy to get wrong. A task group ties their lifetime to one async with block.

Run independent work concurrently

Imagine a page that needs a profile and recent activity from two independent services. With TaskGroup, both requests can run while the current coroutine waits for the group to finish:

import asyncio

async def load_dashboard(user_id):
    async with asyncio.TaskGroup() as group:
        profile_task = group.create_task(fetch_profile(user_id))
        activity_task = group.create_task(fetch_recent_activity(user_id))

    return {
        "profile": profile_task.result(),
        "activity": activity_task.result(),
    }

async def main():
    dashboard = await load_dashboard("u-42")
    print(dashboard)

asyncio.run(main())

When execution leaves the block normally, the group has waited for its child tasks. Their results can then be read from the task objects. This is useful only when the operations are genuinely independent; if the second request needs the first result, await them in sequence instead.

Understand the failure behavior

If a child task fails with an exception other than CancelledError, a task group cancels unfinished siblings and waits for the group to shut down. It then raises the failure or failures together, commonly as an ExceptionGroup. This fail-fast behavior prevents the parent from returning a half-complete result while sibling tasks quietly continue in the background.

Catch grouped failures at a boundary where you can make a meaningful decision. Python 3.11's except* syntax can handle a particular exception type inside an exception group:

try:
    async with asyncio.TaskGroup() as group:
        group.create_task(fetch_profile("u-42"))
        group.create_task(fetch_recent_activity("u-42"))
except* TimeoutError as errors:
    for error in errors.exceptions:
        print("A dashboard request timed out:", error)

Do not catch and discard every exception just to keep the page moving. Decide whether a missing result can be shown as partial data, whether the whole operation should fail, or whether a retry is appropriate. That policy belongs in the application layer that understands the result.

Use timeouts around bounded operations

A task group waits for its children, so a child that never finishes can keep the group open. In Python 3.11 and later, asyncio.timeout() can bound the time spent on a group:

async def load_dashboard(user_id):
    try:
        async with asyncio.timeout(3):
            async with asyncio.TaskGroup() as group:
                profile = group.create_task(fetch_profile(user_id))
                activity = group.create_task(fetch_recent_activity(user_id))
    except TimeoutError:
        return None

    return profile.result(), activity.result()

The timeout cancels the current task; cancellation then causes the group to clean up its children. The context manager turns its own timeout cancellation into TimeoutError, which should be caught outside the timeout block. Choose a deadline based on the application's needs, and distinguish timeouts from other failures if the caller needs different recovery behavior.

Let cancellation do its cleanup

Cancellation is how asyncio asks a task to stop at an await point. If a coroutine owns a resource, use try/finally for cleanup. If it catches CancelledError to perform cleanup, it should normally re-raise it afterward. Swallowing cancellation can interfere with TaskGroup and timeout behavior because those features use cancellation internally.

TaskGroup or create_task?

Use a task group when a set of child tasks belongs to one operation and should finish or be cancelled together. Use a longer-lived task supervisor or another explicit lifecycle design for background work that intentionally outlives the current request. Avoid creating untracked tasks simply to make code appear concurrent.

Task groups do not make blocking code non-blocking. A CPU-heavy function or synchronous network call still blocks the event loop unless it is moved to an appropriate thread or process strategy. Also, concurrency does not automatically make two operations faster if they contend for the same rate limit, connection pool, or external service.

Practical checklist

  • Use TaskGroup for related tasks whose lifetimes should be scoped to one operation.
  • Only run operations concurrently when their inputs do not depend on each other's results.
  • Expect sibling cancellation and grouped exceptions when a child fails.
  • Set timeouts where waiting must be bounded, and catch timeout errors outside the timeout context.
  • Use try/finally for cleanup and normally re-raise cancellation.
  • Keep blocking work off the event loop; an async function is not automatically non-blocking.

Structured concurrency makes task ownership visible: the code that starts a group also waits for and handles its children. Start with a small group of independent I/O operations, define what failure means for the caller, and keep cleanup and timeout behavior explicit.

Further reading

Want a structured Java learning path?

Explore Jaipur Engineers course options to connect Java fundamentals, debugging, backend development and project practice in a guided learning plan.

Explore the Java program   Ask for course guidance