Tasks & Gather

Tasks wrap coroutines for concurrent scheduling on the event loop. asyncio.gather awaits multiple awaitables together - the bread-and-butter of parallel I/O in asyncio.

Recipe

import asyncio
 
async def fetch(n: int) -> int:
    await asyncio.sleep(0.1)
    return n
 
async def main() -> None:
    tasks = [asyncio.create_task(fetch(i)) for i in range(3)]
    print(await asyncio.gather(*tasks))
 
asyncio.run(main())

When to reach for this:

• Concurrent HTTP/DB calls with independent results
• Background tasks alongside request handling
• Fan-in before responding (all data required)
• Optional partial failure with return_exceptions=True
• Bridging callback APIs via create_task

Working Example

import asyncio
 
async def download(url_id: int) -> dict:
    await asyncio.sleep(0.05)
    if url_id == 2:
        raise ValueError("bad response")
    return {"id": url_id, "bytes": 100}
 
async def all_or_nothing() -> None:
    try:
        await asyncio.gather(*(download(i) for i in range(4)))
    except ValueError as exc:
        print("failed", exc)
 
async def collect_errors() -> None:
    results = await asyncio.gather(
        *(download(i) for i in range(4)),
        return_exceptions=True,
    )
    for r in results:
        print(type(r).__name__, r)
 
asyncio.run(all_or_nothing())
asyncio.run(collect_errors())

What this demonstrates:

• Default gather fails fast on first exception
• return_exceptions=True yields exception objects in result list
• Tasks start running as soon as create_task schedules them
• Order of gather results matches submission order, not completion order

Deep Dive

Task vs Coroutine

gather vs TaskGroup

• gather - convenient fan-in, legacy-friendly
• TaskGroup (3.11+) - structured concurrency, auto-cancel siblings on failure

Gotchas

• create_task without reference - task garbage-collected mid-run in edge cases. Fix: keep reference until done.
• gather without return_exceptions in partial success APIs - one failure loses all results. Fix: return_exceptions=True or TaskGroup.
• Blocking code inside tasks - stalls all tasks. Fix: to_thread.
• Unbounded task creation - million tasks exhaust memory. Fix: semaphores, worker pools, batches.
• Fire-and-forget without error handler - task.exception() never retrieved logs warning. Fix: callback or asyncio.create_task wrapper logging failures.

49454e4f4d5f434e4f5904434556494d43451c1c1356181a181c1a1d

Alternatives

FAQs

Related

• Structured Concurrency - TaskGroup
• Asyncio Basics - coroutine primer
• Async HTTP with httpx/aiohttp - concurrent requests
• Debugging Async Code - task leaks

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.