StackPractices
advanced By Mathias Paulenko

Complete Guide to Python Asyncio

Learn asyncio for real workloads: coroutines, tasks, event loops, gather, semaphores, queues, async HTTP clients, websockets, and debugging async code.

Introduction

Asyncio is Python’s framework for writing concurrent code with async/await syntax. A single thread runs an event loop that juggles many coroutines: whenever one of them hits an await that would block on I/O — an HTTP request, a database query, a socket read — it suspends and lets the loop run something else. That is how a single asyncio process holds thousands of open connections while a thread-per-connection design runs out of memory.

Below you’ll find coroutines, tasks, the event loop, concurrency primitives, async HTTP clients, websockets, and debugging — in the order you’ll actually need them. It assumes you’re comfortable with Python and roughly Python 3.10+. Once the patterns here click, the natural next step is the production guide, which covers TaskGroup semantics, cancellation, backpressure, and observability under real load.

When does asyncio actually pay off? I/O-bound work: calling external APIs, fanning out database queries, serving websocket connections. CPU-bound work gains nothing from it, and code that only ever makes one blocking call at a time gains little either — the complexity isn’t free.

Coroutines and async/await

A coroutine is a function declared with async def. Calling it doesn’t run it — it returns a coroutine object, which only executes when it’s awaited or scheduled as a task. This trips up everyone the first week: fetch_data(url) alone does nothing except trigger a RuntimeWarning later.

Inside a coroutine, await is both a suspension point and a yield back to the event loop. await asyncio.sleep(1) releases the thread for a full second; time.sleep(1) blocks it and stalls every other coroutine. Cooperative vs blocking calls: that single distinction is the mental model everything else here builds on.

Basic coroutine

import asyncio

async def fetch_data(url: str) -> str:
    print(f"Fetching {url}")
    await asyncio.sleep(1)  # Simulate I/O
    return f"Data from {url}"

async def main():
    result = await fetch_data("https://example.com")
    print(result)

asyncio.run(main())

asyncio.run() is the right entry point: it creates the loop, runs main() to completion, and closes everything cleanly. You get exactly one asyncio.run() per process — nesting it raises RuntimeError.

Running multiple coroutines sequentially

async def main():
    start = asyncio.get_event_loop().time()

    result1 = await fetch_data("https://api1.example.com")
    result2 = await fetch_data("https://api2.example.com")
    result3 = await fetch_data("https://api3.example.com")

    elapsed = asyncio.get_event_loop().time() - start
    print(f"Sequential: {elapsed:.2f}s")  # ~3.0s

Each await waits for the previous call to finish, so three one-second calls take three seconds. Sequential code like this is a smell: if there’s no data dependency between the calls, they should run concurrently.

Running concurrently with asyncio.gather

async def main():
    start = asyncio.get_event_loop().time()

    results = await asyncio.gather(
        fetch_data("https://api1.example.com"),
        fetch_data("https://api2.example.com"),
        fetch_data("https://api3.example.com"),
    )

    elapsed = asyncio.get_event_loop().time() - start
    print(f"Concurrent: {elapsed:.2f}s")  # ~1.0s
    print(results)

gather() schedules all three coroutines at once and returns their results in argument order — not completion order — which makes mapping results back to inputs trivial. Wall time ends up equal to the slowest call, not the sum of all three.

Error handling with gather

async def fetch_with_error(url: str) -> str:
    if "error" in url:
        raise ValueError(f"Failed to fetch {url}")
    await asyncio.sleep(0.5)
    return f"Data from {url}"

async def main():
    # return_exceptions=True keeps errors as results instead of raising
    results = await asyncio.gather(
        fetch_with_error("https://good.example.com"),
        fetch_with_error("https://error.example.com"),
        fetch_with_error("https://good2.example.com"),
        return_exceptions=True,
    )

    for result in results:
        if isinstance(result, Exception):
            print(f"Error: {result}")
        else:
            print(f"Success: {result}")

Without return_exceptions=True, the first exception propagates and the other tasks are left running — a classic source of “works in dev, leaks in prod” bugs. Decide deliberately: fail fast on the group, or collect per-task errors.

Tasks

An await on a coroutine runs it in place — execution stops there until it finishes. If you want it to start immediately and check the result later, wrap it in a task with asyncio.create_task(). A task is a coroutine scheduled on the event loop — it begins executing on the next loop iteration, so the pattern “create tasks, do other work, await results” is where real concurrency lives.

One caveat the docs understate: keep a reference to every task you create. Since the loop keeps only a weak reference, a task nobody holds onto can get garbage-collected mid-run and die without a word.

Creating tasks manually

async def main():
    # Schedule coroutines as tasks — they start running immediately
    task1 = asyncio.create_task(fetch_data("https://api1.example.com"))
    task2 = asyncio.create_task(fetch_data("https://api2.example.com"))

    # Do other work while tasks run
    print("Tasks started, doing other work...")
    await asyncio.sleep(0.5)

    # Await tasks when you need results
    result1 = await task1
    result2 = await task2
    print(result1, result2)

Task cancellation

async def long_running():
    try:
        while True:
            print("Working...")
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        print("Task cancelled, cleaning up...")
        raise  # Re-raise to propagate cancellation

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

task.cancel() raises CancelledError at the task’s next await point — it doesn’t kill the task at an arbitrary instruction. Catch it, run your cleanup, and re-raise so cancellation actually propagates. Swallowing CancelledError and continuing is the single most common asyncio bug in production code.

Task groups (Python 3.11+)

async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(fetch_data("https://api1.example.com"))
        task2 = tg.create_task(fetch_data("https://api2.example.com"))
        task3 = tg.create_task(fetch_data("https://api3.example.com"))

    # All tasks complete when the context manager exits
    print(task1.result(), task2.result(), task3.result())

With TaskGroup, a failure in one task cancels the siblings — no orphans — and errors surface as an ExceptionGroup instead of being lost. Those are exactly the two things gather gets wrong. On Python 3.11+ this should be your default; keep gather for independent calls where partial failure is fine.

The Event Loop

Everything in asyncio revolves around one piece: the event loop, which is just a scheduler that owns a single thread. It owns exactly one thread, runs callbacks and coroutines one at a time, and switches only at await points. Two rules follow from that: any blocking call freezes every coroutine, and CPU-heavy work between awaits starves the rest of the loop.

flowchart diagram: coroutine created

Running the event loop

# asyncio.run() — recommended for top-level entry point
asyncio.run(main())

# Manual loop control (for advanced use cases)
async def main():
    loop = asyncio.get_running_loop()
    print(f"Running on: {loop}")

# Run in background thread (for mixing sync/async code)
import asyncio
from threading import Thread

class AsyncRunner:
    def __init__(self):
        self.loop = asyncio.new_event_loop()
        self.thread = Thread(target=self.loop.run_forever, daemon=True)
        self.thread.start()

    def submit(self, coro):
        return asyncio.run_coroutine_threadsafe(coro, self.loop).result()

runner = AsyncRunner()
result = runner.submit(fetch_data("https://example.com"))

AsyncRunner is the standard bridge for calling async code from synchronous call sites — the kind you end up writing when a sync codebase grows async needs. run_coroutine_threadsafe is thread-safe; loop.call_soon isn’t.

Semaphores (Limiting Concurrency)

gather over 10,000 URLs means 10,000 simultaneous connections — fast for you, a DDoS for the API you’re calling. A semaphore caps how many coroutines hold the resource at once; the rest queue up. It’s the simplest form of backpressure and the difference between a poller that works and one that gets your IP banned.

async def fetch_with_limit(url: str, semaphore: asyncio.Semaphore) -> str:
    async with semaphore:
        await asyncio.sleep(0.5)
        return f"Data from {url}"

async def main():
    semaphore = asyncio.Semaphore(10)  # Max 10 concurrent

    urls = [f"https://api{i}.example.com" for i in range(100)]
    tasks = [fetch_with_limit(url, semaphore) for url in urls]

    results = await asyncio.gather(*tasks)
    print(f"Fetched {len(results)} URLs")

Pick the limit based on the downstream service’s rate limit, not your local capacity — the bottleneck is almost always on their side. For a full rate-limiting recipe see Limit Async Operations with asyncio.Semaphore.

Queues

asyncio.Queue is the async version of queue.Queue: producers put items, consumers get them, and await handles the blocking when the queue is full or empty. Use maxsize to add backpressure — when the queue fills, producers suspend instead of building unbounded memory pressure.

Producer-consumer pattern

async def producer(queue: asyncio.Queue, items: list):
    for item in items:
        await queue.put(item)
        print(f"Produced: {item}")
    await queue.put(None)  # Sentinel

async def consumer(queue: asyncio.Queue, consumer_id: int):
    while True:
        item = await queue.get()
        if item is None:
            await queue.put(None)  # Pass sentinel to next consumer
            break
        await asyncio.sleep(0.5)
        print(f"Consumer {consumer_id} processed: {item}")
        queue.task_done()

async def main():
    queue = asyncio.Queue(maxsize=10)
    items = list(range(20))

    producers = [asyncio.create_task(producer(queue, items))]
    consumers = [asyncio.create_task(consumer(queue, i)) for i in range(3)]

    await asyncio.gather(*producers)
    await queue.join()
    for c in consumers:
        c.cancel()

The sentinel pattern (None) is the clean way to signal “no more work”. queue.join() waits until every queued item is marked task_done(), which makes shutdown ordering explicit instead of hoping consumers finish in time.

Async HTTP Clients

Most real asyncio code lives here: HTTP calls out to APIs and services. aiohttp and httpx are the two serious options — httpx has the nicer API and supports both sync and async clients, aiohttp is mature and slightly faster in benchmarks. Both matter for the same reason: connections are pooled per client, so create one client and reuse it rather than one per request. And never use requests in async code — it blocks the whole loop.

aiohttp

import aiohttp
import asyncio

async def fetch_url(session: aiohttp.ClientSession, url: str) -> dict:
    async with session.get(url) as response:
        return await response.json()

async def fetch_many(urls: list) -> list:
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_url(session, url) for url in urls]
        return await asyncio.gather(*tasks)

async def main():
    urls = [f"https://api.example.com/users/{i}" for i in range(50)]
    results = await fetch_many(urls)
    print(f"Fetched {len(results)} users")

asyncio.run(main())

httpx (sync + async)

import httpx
import asyncio

async def fetch_with_httpx(urls: list) -> list:
    async with httpx.AsyncClient(timeout=30, limits=httpx.Limits(max_connections=20)) as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.json() for r in responses]

async def main():
    urls = [f"https://api.example.com/items/{i}" for i in range(100)]
    results = await fetch_with_httpx(urls)
    print(f"Got {len(results)} items")

Always set a timeout — a socket that never responds will hang a coroutine forever otherwise. httpx.Limits gives you connection caps equivalent to a semaphore at the client level.

Retry with tenacity

from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
import httpx

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=10),
    retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.RequestError)),
)
async def fetch_with_retry(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.json()

Retries compose well with async code — the coroutine suspends during the backoff instead of blocking a worker. Retry only on transient errors (5xx, timeouts, connection errors), never on 4xx.

Websockets

Websockets are where asyncio earns its keep: thousands of persistent connections on one server, no thread per socket. The websockets library handles the protocol; you write async handlers that look like ordinary coroutines.

Server

import asyncio
import websockets

connected = set()

async def handler(websocket):
    connected.add(websocket)
    try:
        async for message in websocket:
            # Broadcast to all connected clients
            websockets.broadcast(connected, message)
    finally:
        connected.remove(websocket)

async def main():
    async with websockets.serve(handler, "localhost", 8765):
        await asyncio.Future()  # Run forever

asyncio.run(main())

You own the connection set; the library won’t track it for you. The finally block removing the websocket matters as much as the handler logic; skip it and dead sockets accumulate until your broadcast starts raising.

Client

import asyncio
import websockets

async def client():
    uri = "ws://localhost:8765"
    async with websockets.connect(uri) as ws:
        await ws.send("Hello, server!")
        response = await ws.recv()
        print(f"Received: {response}")

asyncio.run(client())

Mixing Sync and Async Code

No real codebase is ever fully async. You’ll have a blocking library (boto3, psycopg2, a PDF parser) that can’t be swapped out. asyncio.to_thread runs it in a worker thread so the loop keeps going — it doesn’t make the call non-blocking, it just moves the block off the loop’s thread.

asyncio.to_thread (Python 3.9+)

import asyncio
import time

def blocking_io(duration: float) -> str:
    time.sleep(duration)  # Blocking call
    return f"Slept for {duration}s"

async def main():
    # Run blocking function in a thread
    result = await asyncio.to_thread(blocking_io, 2.0)
    print(result)

asyncio.run(main())

run_in_executor

async def main():
    loop = asyncio.get_running_loop()

    # Use default thread pool
    result = await loop.run_in_executor(None, blocking_io, 2.0)

    # Use process pool for CPU-bound work
    from concurrent.futures import ProcessPoolExecutor
    with ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, cpu_intensive_work, data)

to_thread is the right default; reach for run_in_executor with a ProcessPoolExecutor when the work is CPU-bound — threads still share the GIL. See also Python Thread Pool Executor for the pure-sync version.

asyncio vs threading vs multiprocessing

Picking the wrong concurrency model hurts more than any asyncio bug. The rule of thumb: asyncio for I/O-bound concurrency in one process, threads for I/O-bound code tied to blocking libraries, processes for CPU-bound work.

asynciothreadingmultiprocessing
Best forHigh-concurrency I/OI/O with sync librariesCPU-bound work
GIL limitedYesYesNo
Overhead per taskVery low (~KB)Medium (~8MB stack)High (process)
Max practical concurrency10k+ connections~hundreds threads~CPU cores × 2
ComplexityMedium (await discipline)Medium (locks, races)High (IPC, serialization)

Debugging Async Code

Async bugs fail quietly: tasks that never ran, coroutines never awaited, deadlocks where everything politely waits for everything else. The debugging toolkit is small but good — turn it all on in development. Two more that save hours: asyncio.all_tasks() lists every task still alive in the loop (useful when “something” is keeping your process from exiting), and task.get_stack() / task.print_stack() shows you exactly where a task is parked.

Enable debug mode

import asyncio
import logging

logging.basicConfig(level=logging.DEBUG)

async def main():
    asyncio.get_running_loop().set_debug(True)

    # Log slow callbacks (> 100ms)
    asyncio.get_running_loop().slow_callback_duration = 0.1

    await some_operation()

asyncio.run(main(), debug=True)

Debug mode catches never awaited warnings, callbacks that block the loop too long, and tasks destroyed while pending. Pair it with PYTHONASYNCIODEBUG=1 to enable it without code changes.

Common pitfalls

# PITFALL 1: Forgetting await — coroutine never runs
async def bad():
    fetch_data("https://example.com")  # Missing await!
    # RuntimeWarning: coroutine 'fetch_data' was never awaited

# PITFALL 2: Blocking call in async code
async def bad():
    time.sleep(5)  # Blocks the entire event loop!

async def good():
    await asyncio.sleep(5)  # Non-blocking

# PITFALL 3: Creating coroutine without scheduling
async def bad():
    coro = fetch_data("https://example.com")
    # Never awaited, never scheduled

# PITFALL 4: Using requests (sync) in async code
import requests

async def bad():
    response = requests.get("https://example.com")  # Blocks event loop!

async def good():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://example.com")

Best Practices

  • Use asyncio.run() as entry point — creates and closes the event loop properly
  • Use asyncio.gather() for concurrent I/O — runs coroutines concurrently, waits for all
  • Limit concurrency with semaphores — prevent overwhelming external services
  • Use asyncio.TaskGroup (3.11+) — better error handling than gather
  • Never call blocking functions in async code — use asyncio.to_thread() instead
  • Use async HTTP clients — aiohttp or httpx, never requests
  • Set timeouts — asyncio.wait_for() or asyncio.timeout() to prevent hangs
  • Handle CancelledError — clean up resources when tasks are cancelled, then re-raise
  • Use return_exceptions=True when you want to handle errors per-task
  • Prefer asyncio.Queue over threading.Queue — works with the event loop
  • Enable debug mode in development — catches missing awaits and slow callbacks
  • Keep references to created tasks — otherwise the GC can cancel them mid-flight

Common Mistakes

  • Forgetting await — coroutine is created but never executed
  • Calling time.sleep() instead of await asyncio.sleep() — blocks the event loop
  • Using requests library in async code — it blocks the event loop
  • Not limiting concurrency — thousands of simultaneous requests overwhelm servers
  • Swallowing CancelledError without re-raising — cancellation silently fails and shutdown hangs
  • Mixing asyncio.run() calls — only one event loop should run per process
  • Not setting timeouts — a slow response hangs the entire application
  • Using asyncio.get_event_loop() in modern code — use asyncio.get_running_loop() or asyncio.run()
  • Creating tasks without keeping references — garbage collector may cancel them
  • Not using async with for resources — connections leak without proper cleanup

See Also

Frequently Asked Questions

When should I use asyncio vs threading vs multiprocessing?

Use asyncio for I/O-bound workloads (HTTP requests, database queries, file I/O) — it handles thousands of concurrent connections on a single thread. Use threading for I/O-bound code stuck with blocking libraries like requests or boto3. Use multiprocessing for CPU-bound work, since the GIL prevents asyncio and threads from using multiple cores.

Can I use asyncio with Flask?

Flask is sync at heart. Since 2.0 it accepts async def views, but those run on a worker thread with limited concurrency — compatibility, not real async. For genuine asyncio-backed request handling go with FastAPI, Quart, or Starlette.

How do I test async code?

The clean way is pytest-asyncio, which lets you write async test functions directly:

import pytest

@pytest.mark.asyncio
async def test_fetch_data():
    result = await fetch_data("https://example.com")
    assert "Data from" in result
What happens if I forget await on a coroutine?

Nothing happens — which is the problem. You get a coroutine object that never runs, plus a RuntimeWarning: coroutine was never awaited somewhere down the line, far from the actual bug. Turn on asyncio debug mode and treat warnings as errors in CI.

Is asyncio faster than threading?

At I/O scale, yes: a coroutine costs a few KB against ~8MB of thread stack, and one loop juggles tens of thousands of connections where a few hundred threads would eat all memory. At low concurrency or on CPU-bound work the gap disappears — and threads are simpler.

Can I nest asyncio.run() or call it from a Jupyter notebook?

No. One loop per thread — asyncio.run() inside a live loop raises RuntimeError. Jupyter keeps its own loop running, which is why top-level await works in notebooks. In scripts, stick to a single asyncio.run() entry point.

How do I stop a hung task?

task.cancel() delivers CancelledError at the task's next await. A task parked in a blocking call — or a coroutine that never awaits — can't be reached, which is why asyncio.wait_for(task, timeout) plus async-native libraries matters more than cancellation itself.