Python Reference ยท Standard Library: Concurrency, Network and Tools
The asyncio module
Reference for Python's asyncio module: coroutines, create_task, gather, TaskGroup, timeout, Queue, Semaphore, to_thread and common mistakes with the event loop.
The asyncio module runs many tasks concurrently on a single thread by switching between them whenever one is waiting. You write functions with async def; inside them, await marks the places where the function can pause so another task can run. This is called cooperative multitasking, and it is ideal for programs that spend their time waiting for I/O: web servers, API clients, chat bots, crawlers.
An event loop drives everything. In a script you start it with asyncio.run(main()), which creates a loop, runs the coroutine main() to completion and closes the loop. A coroutine does nothing until it is awaited or wrapped in a task; calling main() only creates a coroutine object.
import asyncio async def main(): await asyncio.sleep(1) print("done") asyncio.run(main())
The in-browser runner already has a running event loop, so asyncio.run() fails here with a RuntimeError. In these examples you use top-level await main() instead. In a normal script, keep asyncio.run(main()) as the single entry point.
Try it
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.
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.
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.
What is in the module
| Name | Description |
|---|---|
run(coro) |
Runs a coroutine to completion on a fresh event loop; the usual script entry point. Call it once. |
sleep(delay) |
Pauses the current task without blocking the loop. sleep(0) just yields control. |
create_task(coro) |
Schedules a coroutine as a Task. Keep a reference to the task, or it can be garbage collected before it finishes. |
gather(*aws, return_exceptions=False) |
Runs awaitables concurrently and returns their results in argument order. |
TaskGroup() |
Async context manager that waits for all tasks it created and cancels the rest on the first failure (3.11). |
timeout(seconds), wait_for(aw, timeout) |
Raise TimeoutError (and cancel the work) when time runs out. |
wait(tasks, return_when=...) |
Wait for tasks with finer control: FIRST_COMPLETED, FIRST_EXCEPTION, ALL_COMPLETED. |
as_completed(aws) |
Iterate over awaitables in completion order. |
shield(aw) |
Protect an awaitable from cancellation by its caller. |
to_thread(func, *args) |
Run blocking code in a worker thread (3.9). |
Queue, PriorityQueue, LifoQueue |
Async producer-consumer queues. |
Lock, Event, Semaphore, Condition, Barrier |
Async synchronization primitives (not thread-safe). |
get_running_loop(), run_in_executor() |
Access the loop; run blocking functions in an executor. |
open_connection(), start_server() |
Stream-based TCP clients and servers. |
CancelledError, TimeoutError |
Exceptions used for cancellation and timeouts. |
gather() returns a list of results (or exceptions, with return_exceptions=True). create_task() returns a Task with result(), done(), cancel() and add_done_callback().
Usage notes
- Forgetting
awaitis the classic bug:fetch()returns a coroutine object that never runs, and Python warns "coroutine ... was never awaited". - Never block the loop.
time.sleep(),requests.get(), heavy computation or a large file read freezes every task. Useawait asyncio.sleep(), an async library,to_thread()or a process pool. awaitalone is not concurrency. Two awaits in a row run one after the other. Usegather(), aTaskGroupor tasks to overlap them.- Prefer
TaskGroupfor new code. It cancels siblings on failure and reports every error together as anExceptionGroup(catch withexcept*). - Cancellation is an exception.
task.cancel()raisesCancelledErrorinside the task at its nextawait. Do not swallow it; clean up infinallyand re-raise. - Tasks must be referenced. Store the result of
create_task()(in a set or aTaskGroup) so it is not collected mid-run. - One loop per thread, and
asyncio.run()once. You cannot callasyncio.run()from inside a running loop; useawaitthere. - Async primitives are not thread-safe, and an
asyncio.Lockis not athreading.Lock. Useloop.call_soon_threadsafe()when threads must talk to the loop. - Debugging:
asyncio.run(main(), debug=True)reports slow callbacks and unawaited coroutines. - Let
asyncio.run()(orasyncio.Runner) manage the loop. The event loop policy system is deprecated in Python 3.14, and callingget_event_loop()outside a running loop is no longer the way to start one.