Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Awaiting Tasks in Python asyncio

Learn how to await asyncio tasks in Python, retrieve results, handle exceptions, cancel tasks, and avoid common concurrency pitfalls.

~5 min readPython
#asyncio#concurrency#coroutines#event loop
Illustration of a Python asyncio task being awaited on an event loop, showing coroutines suspended and resumed.

To await an asyncio task in Python, use the await keyword on a Task object returned by asyncio.create_task(). The await suspends the current coroutine until the task completes, then returns the task's result or re-raises its exception. Getting this right is the difference between a responsive concurrent application and one that silently blocks or leaks exceptions. The examples below cover the core syntax, runtime behavior, and practical patterns.

What Is an asyncio Task and Why Await It?

An asyncio task is a wrapper around a coroutine that schedules it to run on the event loop. When you call asyncio.create_task(coro), the coroutine is scheduled for execution but does not run immediately. The task runs concurrently with other tasks when the event loop gets control. Awaiting a task suspends the current coroutine until the task finishes, then returns its result or raises its exception.

Tasks are the primary way to run multiple coroutines concurrently. Without tasks, you would have to await each coroutine sequentially, which defeats the purpose of async code. Awaiting a task is how you integrate its outcome into your current flow while allowing other tasks to progress in the meantime.

Creating a Task with asyncio.create_task()

Before you can await a task, you need to create one. The canonical way is asyncio.create_task(), available since Python 3.7. It takes a coroutine and returns a Task object. Here is a minimal example:

python
import asyncio async def fetch_data(): await asyncio.sleep(1) return "data" async def main(): task = asyncio.create_task(fetch_data()) result = await task print(result) asyncio.run(main())

In this example, task is created and scheduled. The await task suspends main() until fetch_data() completes, then assigns the return value to result. The event loop runs fetch_data() concurrently with anything else that is ready, but in this simple case there is nothing else.

Awaiting a Task and Getting Its Result

The await expression on a task returns the coroutine's return value. If the coroutine raises an exception, that exception is re-raised at the await point. This behavior is identical to awaiting the coroutine directly, but with the added benefit that the task can be cancelled or awaited from multiple places.

You can also check whether a task is done without blocking by using task.done(), but that is not the same as awaiting. Awaiting always waits until completion. If you need to wait with a timeout, use asyncio.wait_for(), or wrap the await in asyncio.timeout() (Python 3.11+).

python
async def main(): task = asyncio.create_task(fetch_data()) try: result = await asyncio.wait_for(task, timeout=2) except asyncio.TimeoutError: print("Task took too long")

When a timeout occurs, the task is cancelled automatically. This is a common pattern for bounding the time you spend waiting on a task.

Handling Exceptions When Awaiting a Task

If a task raises an exception, awaiting it propagates that exception to the awaiting coroutine. You must handle it or it will crash your program. The typical approach is a try/except block around the await:

python
async def risky_task(): raise ValueError("bad data") async def main(): task = asyncio.create_task(risky_task()) try: await task except ValueError as e: print(f"Caught: {e}")

If you never await a task that raises an exception, asyncio will log an "exception was never retrieved" warning. This happens because the task's exception is stored internally and only re-raised when the task is awaited. To avoid this, always ensure a task is awaited or explicitly call task.exception() to retrieve the exception.

Awaiting Multiple Tasks with asyncio.gather()

When you have several independent tasks, asyncio.gather() lets you wait for all of them and collects their results in order. It returns a list of results when all tasks complete, or raises the first exception if any task fails.

python
async def fetch_all(): tasks = [asyncio.create_task(fetch_data()) for _ in range(3)] results = await asyncio.gather(*tasks) return results

gather() also accepts coroutines directly, but creating tasks explicitly gives you more control over cancellation and early exit. With the default return_exceptions=False, the first exception is raised from gather() as soon as the failing task completes; the remaining tasks are not cancelled and continue running. Use return_exceptions=True to make gather() wait for every task and return exceptions as values instead:

python
results = await asyncio.gather(*tasks, return_exceptions=True)

This returns a list where exceptions are stored as objects rather than being raised, letting you inspect each outcome individually.

Task Cancellation and Timeouts

Awaiting a task does not prevent it from being cancelled. You can cancel a task with task.cancel(), which raises asyncio.CancelledError inside the coroutine. When you await a cancelled task, the CancelledError is raised at the await point. This is useful for graceful shutdown or for stopping work that is no longer needed.

python
async def main(): task = asyncio.create_task(fetch_data()) task.cancel() try: await task except asyncio.CancelledError: print("Task was cancelled")

If you need to protect a task from cancellation while still allowing it to be awaited, use asyncio.shield(). This wraps the task so that cancelling the wrapper does not cancel the underlying task. This is useful for cleanup operations that must run to completion.

Common Pitfalls When Awaiting Tasks

One frequent mistake is forgetting to await a task and letting it run in the background without ever checking its result. This can lead to unhandled exceptions or tasks that outlive their purpose. Another pitfall is blocking the event loop with synchronous code inside a coroutine. Even if you await a task, the event loop cannot run other tasks while you are blocked in a time.sleep() or a CPU-heavy loop. Use asyncio.sleep() and offload CPU-bound work to a thread pool.

A more subtle issue is awaiting the same task from multiple coroutines. The task itself runs only once, but each coroutine can await the same Task object and receive the same result or exception. If you need to share the result, keep a reference to the task and await that object in each coroutine. Also, be careful with asyncio.gather() when you pass coroutines directly: they are automatically wrapped as tasks, but you lose the ability to cancel them individually before the gather starts.

Performance Considerations of Awaiting Tasks

Awaiting a task has minimal overhead—it is just a suspension and resumption of the coroutine. The real cost is the number of context switches and the scheduling overhead of the event loop. Creating too many tasks can exhaust memory or cause excessive switching. In practice, you should structure your concurrency around the number of I/O-bound operations, not create a task for every tiny piece of work.

When awaiting many tasks, asyncio.gather() is a convenient way to wait for the group. If you need to process results as they arrive, use asyncio.as_completed() instead, which yields awaitables in the order they finish. This allows you to handle each result immediately without waiting for the slowest task.

python
async def main(): tasks = [asyncio.create_task(fetch_data()) for _ in range(5)] for awaitable in asyncio.as_completed(tasks): result = await awaitable print(result)

This pattern is ideal for streaming results or when you want to start processing early. The key is to choose the right tool for your concurrency pattern: gather when you want results from all tasks collected together, as_completed when you need to process results as they finish, and direct await for a single task whose result you need immediately.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.