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.
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.
| asyncio | threading | multiprocessing | |
|---|---|---|---|
| Best for | High-concurrency I/O | I/O with sync libraries | CPU-bound work |
| GIL limited | Yes | Yes | No |
| Overhead per task | Very low (~KB) | Medium (~8MB stack) | High (process) |
| Max practical concurrency | 10k+ connections | ~hundreds threads | ~CPU cores × 2 |
| Complexity | Medium (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 thangather - Never call blocking functions in async code — use
asyncio.to_thread()instead - Use async HTTP clients —
aiohttporhttpx, neverrequests - Set timeouts —
asyncio.wait_for()orasyncio.timeout()to prevent hangs - Handle
CancelledError— clean up resources when tasks are cancelled, then re-raise - Use
return_exceptions=Truewhen you want to handle errors per-task - Prefer
asyncio.Queueover 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 ofawait asyncio.sleep()— blocks the event loop - Using
requestslibrary in async code — it blocks the event loop - Not limiting concurrency — thousands of simultaneous requests overwhelm servers
- Swallowing
CancelledErrorwithout 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 — useasyncio.get_running_loop()orasyncio.run() - Creating tasks without keeping references — garbage collector may cancel them
- Not using
async withfor 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.
Related Resources
Complete Guide to Python Asyncio in Production
Run asyncio in production: event loops, TaskGroup, cancellation, backpressure, debugging, and async patterns that hold under load.
GuideConcurrency Patterns Guide
Production-ready concurrency patterns: thread pools, async/await, producer-consumer, semaphores, actors, circuit breakers in Python, Java, JS, Go, Elixir.
RecipeConcurrent Async Tasks with asyncio.gather and Task Groups
Execute multiple async operations concurrently in Python using asyncio.gather, asyncio.TaskGroup, error handling with return_exceptions, timeouts, and semaphores for rate limiting.
Recipeasyncio.Semaphore: Limit Concurrent API Calls in Python
Use asyncio.Semaphore in Python to cap concurrent API calls, database queries, and resource access with practical rate-limiting patterns.
RecipeParallelize CPU and I/O Work with ThreadPoolExecutor
Use Python's ThreadPoolExecutor for parallel I/O operations, thread-safe result collection, Future callbacks, error handling, and mixing threads with asyncio for blocking work.
DocAsync Task Cancellation Runbook — Python, JS, Go, Java
Runbook for cancelling long-running async tasks without leaks: cooperative signals, cleanup budgets, propagation, and verification in Python, JS, Go, Java.