Asyncio in Python

What is asyncio?

asyncio is Python’s built-in library for asynchronous I/O.

It’s designed for workloads that spend lots of time waiting:

• network requests
• database calls
• file I/O (through async libraries)

Async vs threading vs multiprocessing

• asyncio: single-threaded concurrency using an event loop (great for many I/O tasks)
• threading: multiple threads (good for I/O, simpler when using blocking libs)
• multiprocessing: multiple processes (good for CPU-bound)

Mental model

• async def defines a coroutine.
• await pauses the coroutine so other tasks can run.
• The event loop schedules coroutines and resumes them when they’re ready.

Your first coroutine

first_coroutine.py

import asyncio
 
 
async def main():
    print("Hello")
    await asyncio.sleep(1)
    print("World")
 
 
asyncio.run(main())

When asyncio helps

If you do 100 HTTP requests sequentially, you wait 100 times.

With asyncio you can:

• start many requests
• efficiently wait for them concurrently

When asyncio won’t help

For CPU-heavy loops, asyncio won’t speed things up.

Use:

• multiprocessing
• numpy/vectorization
• compiled extensions

await is not where concurrency comes from

This is the single most common misreading of asyncio. await means wait here until this finishes. Written in a loop, it is exactly as sequential as ordinary code:

diagram Diagram mermaid

  flowchart TD
  A["await one after another"] --> A1["task 1 ... 0.2s"]
  A1 --> A2["task 2 ... 0.2s"]
  A2 --> A3["task 3 ... 0.2s"]
  A3 --> AR["total 1.005s"]
  B["asyncio.gather"] --> B1["task 1, 2, 3 all handed
to the loop together"]
  B1 --> B2["loop switches whenever
one of them waits"]
  B2 --> BR["total 0.215s"]

Measured, five coroutines each sleeping 0.2 s:

	time	speedup
for i in range(5): await work(i)	1.005 s	1.0×
await asyncio.gather(*[work(i) for i in range(5)])	0.215 s	4.7×

Concurrency comes from handing the loop several things at once — gather, create_task, or a TaskGroup. An await on its own just yields control until that one operation is done.

Calling a coroutine function does nothing

not_running.py

import asyncio, inspect
 
async def work(name):
    await asyncio.sleep(0.1)
    return name
 
c = work("a")                     # no code has run yet
print(type(c).__name__)           # coroutine
print(inspect.iscoroutine(c))     # True
print(asyncio.run(c))             # 'a'   <- now it runs

A coroutine object is a description of work. Forgetting to await one is why RuntimeWarning: coroutine ... was never awaited exists — the call looked like it did something and did not.

create_task schedules, a bare coroutine waits to be asked

task_vs_coro.py

log = []
 
async def note(n):
    log.append(f"{n} started")
    await asyncio.sleep(0.05)
 
t1 = asyncio.create_task(note("task"))   # handed to the loop right away
co = note("coro")                        # just an object; nothing scheduled
await asyncio.sleep(0.01)
print(log)                               # ['task started']   <- only one of them began

See it move

One thread, one loop. A coroutine runs until it hits an await, hands control back, and the loop picks whoever is ready. Nothing here is parallel — it is interleaved, and that is enough when the work is waiting.

sketch How the event loop interleaves coroutines p5.js Pause Restart

Each coroutine runs until it awaits, then yields to the loop. With gather, three coroutines overlap their waiting; awaited one by one they cannot.

One blocking call freezes everything

Because there is only one thread, any function that blocks without awaiting stops the whole loop — every other coroutine included:

blocking.py

async def good():
    await asyncio.sleep(0.3)      # yields to the loop
 
async def blocker():
    time.sleep(0.3)               # WRONG inside async: nothing yields

two coroutines running together	measured
both await asyncio.sleep(0.3)	0.310 s — overlapped
both time.sleep(0.3)	0.602 s — serialized

The rule that follows

Inside async def, every slow call must be awaitable. A plain requests.get, time.sleep, open().read() on a big file, or a heavy CPU loop will stall every other task on the loop. Push unavoidable blocking work to await asyncio.to_thread(fn, ...).

gather returns in argument order

order.py

res = await asyncio.gather(timed("slow", 0.3), timed("fast", 0.05), timed("mid", 0.15))
print(res)              # ['slow', 'fast', 'mid']   <- the order you passed them
# actual completion order was ['fast', 'mid', 'slow']

Results line up with your arguments, which makes zip(urls, results) safe. If you want results as they arrive, use asyncio.as_completed.

When one of them fails

errors.py

await asyncio.gather(work("ok"), bad())
# ValueError: boom      <- the first exception propagates immediately
 
await asyncio.gather(work("ok"), bad(), return_exceptions=True)
# ['ok', ValueError('boom')]    <- collected instead of raised

With return_exceptions=True you always get one entry per input, and it is your job to check which entries are exceptions.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. Five coroutines each sleep 0.2 s. Awaiting them one per loop iteration took 1.005 s; gather took 0.215 s. What does that show?

   A gather runs the coroutines on separate threads B await means 'wait here', so concurrency comes from handing several coroutines to the loop at once C asyncio.sleep is faster inside gather D the loop caches repeated coroutine calls
   pch.quizShowAnswer

   B — await means 'wait here', so concurrency comes from handing several coroutines to the loop at once — A loop of awaits is sequential by definition. gather submits all five, so their waiting overlaps. Everything still runs on one thread.

2. You write c = work('a') where work is an async def, and never await c. What has happened?

   A work ran and its result was discarded B work started in the background C nothing ran; c is a coroutine object and Python warns it was never awaited D a TypeError, since async functions cannot be called directly
   pch.quizShowAnswer

   C — nothing ran; c is a coroutine object and Python warns it was never awaited — Calling an async function builds a coroutine object describing the work. inspect.iscoroutine(c) is True and no body has executed until it is awaited or scheduled.

3. Two coroutines that both call time.sleep(0.3) took 0.602 s, while two that await asyncio.sleep(0.3) took 0.310 s. Why?

   A time.sleep is less precise B time.sleep blocks the single thread the loop runs on, so nothing else can proceed C asyncio.sleep uses multiple cores D the loop retries blocking calls
   pch.quizShowAnswer

   B — time.sleep blocks the single thread the loop runs on, so nothing else can proceed — asyncio is single-threaded. A blocking call never yields control, so the loop cannot switch to the other coroutine. Use asyncio.to_thread for work you cannot make awaitable.

4. gather is given slow (0.3 s), fast (0.05 s) and mid (0.15 s), in that order. What does it return?

   A results in completion order: fast, mid, slow B results in argument order: slow, fast, mid C an unordered set of results D only the first result to arrive
   pch.quizShowAnswer

   B — results in argument order: slow, fast, mid — gather preserves argument order regardless of when each finished, which is what makes zip(inputs, results) correct. Use asyncio.as_completed if you want them as they arrive.

🧪 Try It Yourself

Exercise 1 – Your First Coroutine

pch.exerciseTag pch.exerciseTitle

Exercise 2 – await asyncio.sleep

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Gather Two Coroutines

pch.exerciseTag pch.exerciseTitle