Skip to content
Tutorials Center
My learning

Topics

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.

Python
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

Python Sequential vs concurrent

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.

Python Tasks, TaskGroup, timeouts and errors

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.

Python Queue, Semaphore and Event

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 await is 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. Use await asyncio.sleep(), an async library, to_thread() or a process pool.
  • await alone is not concurrency. Two awaits in a row run one after the other. Use gather(), a TaskGroup or tasks to overlap them.
  • Prefer TaskGroup for new code. It cancels siblings on failure and reports every error together as an ExceptionGroup (catch with except*).
  • Cancellation is an exception. task.cancel() raises CancelledError inside the task at its next await. Do not swallow it; clean up in finally and re-raise.
  • Tasks must be referenced. Store the result of create_task() (in a set or a TaskGroup) so it is not collected mid-run.
  • One loop per thread, and asyncio.run() once. You cannot call asyncio.run() from inside a running loop; use await there.
  • Async primitives are not thread-safe, and an asyncio.Lock is not a threading.Lock. Use loop.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() (or asyncio.Runner) manage the loop. The event loop policy system is deprecated in Python 3.14, and calling get_event_loop() outside a running loop is no longer the way to start one.