Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python async for vs for: Choosing the Right Loop

Understand the difference between `async for` and `for` in Python, when each loop is required, and how to avoid common asyncio iteration pitfalls.

~5 min readPython
#async iteration#asyncio#Python loops#async generators
Diagram contrasting a synchronous for loop with an async for loop over an asynchronous stream

The difference between async for and for comes down to the type of iterable you are consuming. A regular for loop drives the synchronous iteration protocol (__iter__ and __next__). An async for loop drives the async iteration protocol (__aiter__ and __anext__), where each step returns an awaitable. Using the wrong loop on the wrong iterable raises a TypeError immediately, so knowing which one your data source requires is not optional.

What async for Changes About Iteration

An async iterable is any object whose __aiter__() returns an async iterator. An async iterator's __anext__() returns an awaitable that resolves to the next item or raises StopAsyncIteration when exhausted. The async for statement drives that protocol, awaiting each __anext__() call before executing the loop body.

python
async def process_stream(stream): async for chunk in stream: await handle(chunk)

Here stream must be an async iterable. The loop obtains an async iterator by calling stream.__aiter__(), then awaits __anext__() for each iteration. This allows the event loop to run other tasks while waiting for the next chunk to arrive. This is the key difference from a synchronous for, which blocks the thread until the next item is produced.

Async generators are the easiest way to create async iterables. A function that contains yield and is defined with async def becomes an async generator:

python
async def read_lines(reader): while line := await reader.readline(): yield line

You can then consume it with async for:

python
async for line in read_lines(reader): print(line)

The async for loop handles the async generator's lifecycle, including calling aclose() when the loop exits early.

Why a Regular for Loop Fails on Async Iterables

A synchronous for loop drives the synchronous iteration protocol: it calls iter() to get an iterator and then calls __next__() on that iterator for each item. An async iterable uses a different protocol, __aiter__() and __anext__(). Attempting to use for on an async iterable raises:

python
async def gen(): yield 1 # This raises TypeError: 'async_generator' object is not iterable for item in gen(): print(item)

The same error occurs if you try to call iter() on an async generator. The fix is to switch to async for inside an async def function. The reverse is also true: using async for on a synchronous iterable fails because the object does not implement __aiter__.

This strict separation exists because the two iteration protocols have different execution models. Synchronous iteration runs entirely on the calling thread and blocks between items. Async iteration yields control back to the event loop between items, which is essential for I/O-bound operations but impossible to emulate with a blocking for loop.

When to Use async for vs for

The decision is driven by the data source, not by preference. Use async for when the iterable is asynchronous: an async generator, a network stream, a database cursor that returns rows asynchronously, or any custom object implementing the async iteration protocol (__aiter__ and __anext__). Use for when the iterable is synchronous, for example a list, tuple, set, dictionary, or a synchronous generator.

python
# Synchronous iterable: use for items = [1, 2, 3] for item in items: print(item) # Asynchronous iterable: use async for import asyncio async def async_items(): for i in range(3): await asyncio.sleep(0.1) yield i async def main(): async for item in async_items(): print(item) asyncio.run(main())

A common mistake is to wrap a synchronous iterable in async for just because you are inside an async function. That is unnecessary and will raise a TypeError. Conversely, calling a synchronous function that returns a list and then trying to iterate it with async for is also wrong. The loop type must match the iterable's protocol.

If you have a synchronous iterable that produces values slowly because of I/O, convert it to an async iterable by defining an async generator that awaits a non-blocking I/O operation, or wrap blocking calls with asyncio.to_thread(...). Do not use async for on a plain list.

Performance and Concurrency Considerations

async for does not make your loop concurrent. It awaits each iteration sequentially, meaning the loop body runs to completion before the next item is fetched. The benefit is that while the __anext__() call is pending, the event loop can schedule other tasks. This reduces wall-clock time for I/O-bound workloads because waiting for one item does not block the entire process.

However, if you need to process multiple items concurrently, async for alone is not enough. You must create tasks explicitly:

python
async def process_all(items): tasks = [asyncio.create_task(handle(item)) for item in items] await asyncio.gather(*tasks)

Here items is a synchronous list, and handle is an async function. This pattern launches all handle calls concurrently. Using async for with an async generator that yields items one by one and then awaiting each handle sequentially would be slower if the operations are independent.

Memory usage also differs. A synchronous for over a large list keeps the entire list in memory. An async generator can yield items lazily, so async for can process a stream without loading everything at once. This is valuable for reading large files, network responses, or database result sets that do not fit in memory.

Common Patterns and Pitfalls

One frequent pitfall is attempting to use async for outside an async def function. The async for statement is only valid inside an async function or an async generator. Running it in a regular function raises a SyntaxError.

Another issue is mixing synchronous and asynchronous code inside the loop body. If the loop body performs blocking I/O, such as time.sleep() or requests.get(), it will block the event loop and negate the benefit of async for. Use await asyncio.sleep() and async HTTP clients instead.

Error handling inside async for works like a normal loop. Wrap the loop in try/except to catch exceptions raised by __anext__() or the loop body. You do not need to catch StopAsyncIteration; the loop handles it automatically as the normal end of iteration.

python
async def safe_iterate(stream): try: async for item in stream: await process(item) except Exception as exc: log_error(exc)

If you need to break out of an async for loop early, the loop will call aclose() on the async iterator, which allows the generator to run any finally blocks.

Another subtlety: you cannot use yield inside an async for loop unless the containing function is an async generator. If you need to transform an async iterable into another async iterable, define an async generator and yield from within it.

Choosing the Right Loop for Your Data Source

The table below summarizes the decision based on the iterable type.

Iterable typeLoop to useExampleWhen to use
Synchronous iterable (list, dict, set, sync generator)forfor x in [1,2,3]In-memory data, CPU-bound iteration
Async iterable (async generator, async stream)async forasync for x in async_gen()I/O-bound streaming, lazy data production
Synchronous generator that performs blocking I/OConvert to async firstasync for x in async_wrapper(sync_gen)When you must integrate blocking code into asyncio
Async iterable that needs concurrent processingasync for + asyncio.gatherasync for x in source: tasks.append(asyncio.create_task(handle(x))) + await asyncio.gather(*tasks)Independent per-item async operations

For most application code, the rule is simple: if the object you are iterating over was created by an async def function that uses yield, or if it implements the async iteration protocol (__aiter__/__anext__), use async for. Otherwise, use for. This rule prevents the most common TypeError and keeps your event loop responsive.

When you control the data source, prefer async generators for lazy streaming and synchronous generators for CPU-bound or small in-memory sequences. If you need to adapt a synchronous iterable to an async context, wrap it in an async generator that awaits a non-blocking operation or uses asyncio.to_thread to avoid blocking the loop.

Finally, remember that async for is a sequential construct. It does not parallelize iteration. For true concurrency, combine it with task creation and asyncio.gather or use higher-level patterns like asyncio.Queue to distribute work across workers. Understanding this distinction will help you write asyncio code that is both correct and efficient.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.