Python async/await: Asynchronous Programming with asyncio
What you’ll learn
Section titled “What you’ll learn”- How
async defandawaitdefine coroutines and howasyncio.rundrives them. - How
asyncio.gatherruns several awaitables concurrently andasyncio.create_taskschedules one to run in the background. - Why async helps I/O-bound work and starves CPU-bound work.
- How to add timeouts, cancellation, and a concurrency limit with a semaphore.
- How async generators stream results without buffering everything in memory.
Summary
Section titled “Summary”async/await is Python’s syntax for cooperative concurrency, built on the asyncio module. An async def function is a coroutine that runs until it hits an await, then yields control so other coroutines can run on the same event loop. This lets a single thread handle thousands of simultaneous I/O operations by switching whenever one of them waits. The feature arrived with async/await keywords in Python 3.5 and has been the standard way to write concurrent I/O ever since. It does not create new threads and does not speed up CPU-bound code.
The problem it solves
Section titled “The problem it solves”The problem is latency hidden behind blocking calls. OrdersPortal needs to fetch several orders from a warehouse service before it can render a page. Fetched one at a time, each call blocks the whole process until its response arrives, so ten calls that each take 100 milliseconds take a full second. Concurrency lets those waits overlap.
Sequential, blocking code:
import time
def fetch_order(order_id): time.sleep(0.1) # simulate a 100 ms network call return {"id": order_id, "total": order_id * 10}
def fetch_all(order_ids): return [fetch_order(i) for i in order_ids]
start = time.perf_counter()results = fetch_all(range(1, 6))elapsed = time.perf_counter() - startprint(f"{len(results)} orders in {elapsed:.3f}s")# 5 orders in 0.500s <- waits stack end to endThe five calls take about half a second because each time.sleep blocks the next from starting. The same work, written to overlap the waits, finishes in roughly the time of a single call.
How it works
Section titled “How it works”An async def function returns a coroutine object instead of running immediately. You run it on an event loop, most simply with asyncio.run. Inside a coroutine, await suspends until the awaited awaitable finishes, handing control back to the loop so other tasks can progress.
import asyncio
async def fetch_order(order_id): await asyncio.sleep(0.1) # simulate an awaitable network call return {"id": order_id, "total": order_id * 10}
async def fetch_all(order_ids): # gather runs the coroutines concurrently and preserves order return await asyncio.gather(*(fetch_order(i) for i in order_ids))
async def main(): start = time.perf_counter() results = await fetch_all(range(1, 6)) elapsed = time.perf_counter() - start print(f"{len(results)} orders in {elapsed:.3f}s")
import timeasyncio.run(main())# 5 orders in 0.100s <- waits overlapThe key change is asyncio.gather, which schedules every fetch_order coroutine at once. The loop runs them all, and each await asyncio.sleep yields, so the five 100-millisecond waits run together and the total drops to about 100 milliseconds.
asyncio.create_task schedules a coroutine to run on the loop without awaiting it right away. Use it when you want a coroutine to start working in the background while you do something else, then await the task later to collect its result. If you never await or cancel a task, the loop warns about a never-awaited coroutine.
Async generators, declared with async def and yield, produce values lazily and can await between yields. They are the streaming counterpart to regular generators: you consume them with async for.
import asyncio
async def order_stream(count): for i in range(1, count + 1): await asyncio.sleep(0.05) yield {"id": i}
async def main(): async for order in order_stream(3): print(order)
asyncio.run(main())# {'id': 1}# {'id': 2}# {'id': 3}The generator emits each order as soon as it is ready, so the caller can begin processing before the whole batch is fetched. The values are never all held in memory at once.
Realistic example
Section titled “Realistic example”OrdersPortal renders a customer page by fetching the customer record, their orders, and their shipping history from three services. Fetched sequentially the page is slow; fetched concurrently with asyncio.gather it is fast, and a timeout keeps one slow service from stalling the whole page.
import asyncio
async def fetch_customer(customer_id): await asyncio.sleep(0.05) return {"id": customer_id, "name": "Acme"}
async def fetch_orders(customer_id): await asyncio.sleep(0.08) return [{"id": 1023, "total": 1500.0}, {"id": 1024, "total": 800.0}]
async def fetch_shipping(customer_id): await asyncio.sleep(0.06) return [{"order_id": 1023, "carrier": "FedEx"}]
async def load_page(customer_id): # run all three fetches concurrently, cap total wait at 0.5 s customer, orders, shipping = await asyncio.wait_for( asyncio.gather( fetch_customer(customer_id), fetch_orders(customer_id), fetch_shipping(customer_id), ), timeout=0.5, ) return {"customer": customer, "orders": orders, "shipping": shipping}
async def main(): page = await load_page(1) print(f"{page['customer']['name']}: {len(page['orders'])} orders, {len(page['shipping'])} shipments")
asyncio.run(main())# Acme: 2 orders, 1 shipmentsThe three fetches overlap inside asyncio.gather, and asyncio.wait_for raises TimeoutError if the group takes longer than half a second. That bound protects the page from one degraded service.
Production patterns
Section titled “Production patterns”- Limit concurrency with a semaphore. Launching a thousand simultaneous HTTP calls can overwhelm the server or exhaust connections. Wrap each call in an
asyncio.Semaphoreto cap how many run at once. - Always set a timeout. An awaited call with no timeout can hang forever and stall the event loop. Use
asyncio.wait_foror the timeout argument on the HTTP client. - Handle cancellation cleanly. A cancelled coroutine raises
asyncio.CancelledError; catch it, release resources, and re-raise so the cancellation propagates. Code that swallows the error breaks the shutdown contract. - Drive the loop one way. Call
asyncio.runat the top of your program and let everything flow from there. Mixing manualloop.run_until_completecalls withasyncio.runleads to “event loop is closed” errors.
Common mistakes
Section titled “Common mistakes”- Forgetting
await. Callingfetch_order(1)withoutawaitreturns a coroutine object and runs nothing. The bug is silent until you try to use the result. - Calling blocking code in a coroutine. A
time.sleepor a synchronousrequests.getinside anasync defblocks the entire loop, freezing every other coroutine. Useawait asyncio.sleepor an async HTTP client. - Awaiting coroutines sequentially instead of gathering.
await a(); await b()runs them one after another.await asyncio.gather(a(), b())runs them concurrently. The difference is the whole point of async. - Creating tasks you never await.
asyncio.create_taskschedules work, but if you drop the reference the task can be garbage-collected before it finishes. Keep the returned task and await it. - Using async for CPU-bound work. Async overlaps waits, not computation. A tight CPU loop never yields, so no other coroutine runs.
When to use it and when not to
Section titled “When to use it and when not to”| Situation | Right tool | Why |
|---|---|---|
| Many simultaneous network or disk calls | asyncio |
One thread overlaps thousands of waits |
| CPU-heavy computation | multiprocessing |
Async cannot parallelize CPU work on one thread |
| A few blocking calls in mostly-sync code | threads | Simpler than rewriting to async |
| Mixing async and sync libraries | threads or run_in_executor |
Keeps the sync library from blocking the loop |
Async is a concurrency model, not a parallelism model. It wins when your program spends its time waiting, and it actively hurts when it spends its time computing.
Compatibility
Section titled “Compatibility”async/await keywords arrived in Python 3.5. asyncio.run arrived in Python 3.7 and is the supported entry point. Top-level await in the REPL arrived in Python 3.8. Async generators arrived in Python 3.6. The examples here run on Python 3.9 and later. For HTTP, the standard library has no async client; use httpx or aiohttp, both of which require pip install.
Interview questions
Section titled “Interview questions”1. What does await actually do?
It suspends the current coroutine and returns control to the event loop, which can run other ready coroutines. When the awaited awaitable completes, the loop resumes the suspended coroutine with the result. The thread never blocks on the wait.
2. Why does asyncio.gather speed up the fetches?
It schedules every coroutine at once, so their waits overlap on the single event loop. Each await inside one coroutine is a chance for the loop to progress another, so five 100-millisecond waits finish in roughly 100 milliseconds instead of 500.
3. What goes wrong if you call a blocking function inside a coroutine? The blocking call does not yield, so the event loop cannot switch to other coroutines while it runs. Every concurrent task stalls until the blocking call returns, defeating the purpose of async and turning concurrency back into sequential execution.
4. Senior scenario: your async service occasionally hangs and never responds. How do you find it?
Look for an unbounded await: a network call with no timeout, or a queue the producer fills faster than the consumer drains. Add asyncio.wait_for with a timeout around every external call, log when tasks are created and cancelled, and instrument the loop with asyncio.get_event_loop().set_debug(True) to surface slow callbacks. The usual cause is one coroutine stuck in a blocking call that starves the loop.
Key takeaways
Section titled “Key takeaways”async defdefines a coroutine;awaitsuspends it;asyncio.rundrives it.asyncio.gatherruns awaitables concurrently;asyncio.create_taskruns one in the background.- Async overlaps I/O waits on one thread; it does not parallelize CPU work.
- Never call blocking code in a coroutine, and always set a timeout on external calls.
- Use
httpxoraiohttpfor async HTTP; the standard library has no async client.
Related pages
Section titled “Related pages”- threading vs multiprocessing — when threads or processes beat async.
- the GIL — why CPU threads do not run in parallel in CPython.
- iterators and generators — the synchronous generators that async generators extend.
- context managers — async context managers for resources held across awaits.
Official references
Section titled “Official references”- Python 3 —
asynciomodule — the event loop and primitives. - Python 3 — Coroutines and Tasks —
async def,await,gather,create_task. - PEP 492 — Coroutines with async and await syntax — the original proposal.
- Real Python — Async IO in Python — a practical walk-through.