Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 149 ยท Beyond the Basics

Async Programming with asyncio

Learn async programming in Python with asyncio. Write coroutines with async and await, run work concurrently with tasks, gather and TaskGroup, and add timeouts.

Many programs spend most of their time waiting: for a web server to answer, for a database query to finish, for a file to arrive over the network. While one request is waiting, the processor sits idle. Async programming lets a single program start many of those waits at once and pick up each result as soon as it is ready.

Python's built-in tool for this is the asyncio module, together with two keywords: async and await. In this lesson you will write coroutines, run them one after another and then side by side, manage tasks, handle errors and timeouts, and learn the one rule that trips up nearly every beginner: never block the event loop.

The idea: one cook, many pots

Picture a cook making pasta, sauce and tea. A bad cook boils the water, stares at it for ten minutes, then starts the sauce. A good cook puts the water on, starts the sauce while the water heats, and fills the kettle in between. There is still only one cook, but no time is wasted waiting.

asyncio works like the good cook. A single thread runs an event loop. Each piece of async code runs until it reaches a point where it has to wait. There it says "wake me up when this is done" and hands control back to the loop, which runs something else in the meantime.

This is concurrency (juggling many tasks), not parallelism (doing many things at the same instant on several processor cores). Async code shines when the work is mostly waiting, such as network calls. For heavy number crunching, it gives no speed-up at all.

Coroutines: async def and await

Put async in front of def and you get a coroutine function. Calling it does not run the body. It returns a coroutine object, a paused piece of work that runs only when something awaits it:

Python Calling vs awaiting a coroutine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A few rules to remember:

  • await can only appear inside an async def function (with one exception in this editor, explained next).
  • You can only await awaitables: coroutines, tasks and a few other async objects.
  • asyncio.sleep() is the async version of time.sleep(). It pauses this coroutine and lets the loop run others.

Notice the last line await pending, written at the top level of the program. That needs some explaining.

How async programs start

Something has to create the event loop and run your first coroutine. In a normal Python script you do that with asyncio.run(), usually at the very bottom of the file:

Python
import asyncio

async def main():
    print("Working...")
    await asyncio.sleep(1)
    print("Done.")

if __name__ == "__main__":
    asyncio.run(main())

asyncio.run(main()) creates a fresh event loop, runs main() until it finishes, then closes the loop. Your whole async program lives inside main() and the coroutines it awaits.

The editors on this site work differently. Python runs inside your browser, and the browser already has an event loop running (it's the same loop that handles clicks and timers on every web page). asyncio.run() refuses to start a second loop inside a running one, so it fails here with a RuntimeError. Try it:

Python asyncio.run() inside a running loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Because a loop is already running, the editor lets you write await at the top level, outside any function. Jupyter notebooks and the python -m asyncio REPL behave the same way. So in every example below, the last line is await main(). When you copy the code into a .py file on your own computer, replace that line with asyncio.run(main()).

Same code, two launchers. Everything inside main() is identical in both worlds. Only the single line that starts the program changes: await main() here, asyncio.run(main()) in a script.

Sequential vs concurrent

Here is the payoff. Below, three "downloads" each take a moment. First we await them one at a time, then we start them all together with asyncio.gather():

Python One after another, then all at once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The sequential version takes about the sum of the waits (1.5 seconds). The concurrent version takes about as long as the slowest one (0.6 seconds), because all three waits overlap.

Two details about gather():

  • It returns the results in the same order you passed the coroutines in, no matter which one finished first.
  • If one of them raises an exception, gather() raises it too. Pass return_exceptions=True to get exceptions back as values in the result list instead.

Tasks

A coroutine object just sits there until someone awaits it. A task is different: asyncio.create_task() wraps a coroutine and schedules it right away. It starts running at the next chance the loop gets, and you await the task later to collect its result.

Python Starting tasks in the background

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Keep a reference to every task you create (here, the variables tea and coffee). The event loop only holds a weak reference, so a task you never store or await can be garbage-collected before it finishes.

Task groups

Since Python 3.11, the recommended way to run a batch of tasks is asyncio.TaskGroup. It is an async context manager (async with). Every task created inside the block is awaited automatically when the block ends, and if one task fails, the group cancels the others:

Python TaskGroup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

async with and async for are the async versions of the context managers and loops you already know. They can only appear inside async code.

Handling errors

Exceptions in coroutines travel up through await just like they do through normal function calls, so plain try/except works. With many tasks you have two choices.

With gather(..., return_exceptions=True), each failure comes back as a value in the result list. With a TaskGroup, the failures are bundled into an ExceptionGroup, which you catch with except*:

Python Failures with gather and TaskGroup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Exception groups are covered briefly in Custom Exceptions. For now, read except* LookupError as "handle every LookupError inside the group".

Timeouts

A network call that never answers should not freeze your program. asyncio.timeout() (Python 3.11+) cancels whatever is inside its block once the time runs out and raises TimeoutError:

Python Giving up after a deadline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Limiting concurrency

Starting 10,000 requests at once can overwhelm a server (and get you blocked). An asyncio.Semaphore lets only a fixed number of coroutines into a section at a time:

Python At most two at a time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output shows uploads starting in pairs: a third one only begins after an earlier one finishes. The * in gather(*...) unpacks the generator into separate arguments.

Don't block the event loop

All coroutines share one thread. When a coroutine awaits, others get their turn. When a coroutine does slow work without awaiting, nobody else can run. These are the usual culprits:

Python
async def bad():
    time.sleep(2)                  # freezes every other coroutine for 2 seconds
    requests.get(url)              # a regular, blocking HTTP call does the same
    sum(i * i for i in range(10**9))   # long CPU work never gives up control

async def good():
    await asyncio.sleep(2)                          # async sleep
    data = await asyncio.to_thread(read_big_file)   # run blocking code in a thread
  • Use async libraries for I/O: for example httpx or aiohttp for HTTP, and async database drivers. Regular libraries such as requests block.
  • Wrap unavoidable blocking calls in asyncio.to_thread() so they run in a worker thread while the loop keeps going.
  • For heavy computation, use processes (concurrent.futures.ProcessPoolExecutor or multiprocessing) instead of async.

A missing await is a silent bug. Writing asyncio.sleep(1) or save_data() without await creates a coroutine object and throws it away. Nothing happens, and Python only prints a RuntimeWarning: coroutine ... was never awaited. If an async function "does nothing", check for a missing await first.

When to use asyncio

Async code adds complexity, so reach for it when it pays off:

  • Good fits: web servers and API clients handling many connections, chat bots, web scrapers, anything that talks to many network services at once.
  • Poor fits: short scripts that do one thing at a time, and CPU-heavy work like image processing or math.

If you are not sure, start with ordinary synchronous code. You can move the slow, waiting parts to async later.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens when you call fetch() if it is defined with async def fetch():?

    Calling a coroutine function only creates a coroutine object. The body runs when you await it or wrap it in a task.
  2. 2. Three coroutines wait 1, 2 and 3 seconds. Roughly how long does await asyncio.gather(...) of all three take?

    The waits overlap, so the total is about the length of the slowest one, 3 seconds. Cores don't matter, since asyncio runs on a single thread.
  3. 3. Why does asyncio.run(main()) fail in this site's editor?

    asyncio.run() creates and runs a new loop. Inside an already-running loop it raises RuntimeError, so the editor lets you use top-level await main() instead.
  4. 4. Which line inside a coroutine blocks every other coroutine?

    time.sleep() pauses the whole thread, and with it the event loop. The other three let the loop keep running other work.
  5. 5. What does asyncio.TaskGroup do when one of its tasks raises an exception?

    A task group cancels its other tasks and reports every failure together in an ExceptionGroup, which you can handle with except*.

Summary

  • async def defines a coroutine function; calling it returns a coroutine object that runs when awaited.
  • await pauses the current coroutine and lets the event loop run others while it waits.
  • Scripts start with asyncio.run(main()). In this browser editor a loop is already running, so use top-level await main() instead.
  • asyncio.gather() and asyncio.TaskGroup run many coroutines concurrently; create_task() schedules one in the background.
  • asyncio.timeout() and wait_for() add deadlines; Semaphore limits how many run at once.
  • Never block the loop with time.sleep(), blocking I/O or long computations; use async libraries, asyncio.to_thread() or processes.

Next: Threads, Processes and concurrent.futures.