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

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:

  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:

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

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

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.

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:

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

gather returns in argument order

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

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

🧪 Try It Yourself

Exercise 1 – Your First Coroutine

Press Run to see what your code prints.

Exercise 2 – await asyncio.sleep

Press Run to see what your code prints.

Exercise 3 – Gather Two Coroutines

Press Run to see what your code prints.