Python asyncio.TaskGroup: A Practical Guide
Learn Python 3.11 TaskGroup patterns for concurrent coroutines, sibling cancellation, exception groups, timeouts, and cleanup.
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
TaskGroupfor 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/finallyfor cleanup and normally re-raise cancellation. - Keep blocking work off the event loop; an
asyncfunction 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.