In Python 3.10 and newer, aiter(async_iterable) returns an asynchronous iterator. It is the async counterpart of iter(): it calls the object's __aiter__() method. You then awaitanext() on the result to get items one at a time.
An async for loop does this automatically, so you only need aiter() when you want to step through an async stream by hand. Async code needs an event loop; the examples start one with asyncio.run(main()).
aiter() is a built-in function: it lives in the builtins module, so it is always available without an import. New in Python 3.10. On Python 3.8 and 3.9 the name does not exist (NameError); call obj.__aiter__() directly there.
Syntax
Call it inside an async def function.
python
async def main():
iterator = aiter(async_iterable)
first = await anext(iterator)
Call
What it does
aiter(agen())
An async iterator over an async generator.
await anext(aiter(x))
The first item.
aiter(obj) is obj
Often True when obj is already an async iterator.
aiter([1, 2])
Raises TypeError: not an async iterable.
aiter() itself is a normal function call, not a coroutine, so it does not need await.
Library declarations
python
aiter(async_iterable, /)
# calls type(async_iterable).__aiter__(async_iterable); new in Python 3.10
Parameters
Parameter
Description
async_iterable
Required. An object with __aiter__(), such as an async generator.
Return Value
Return Value
Description
async iterator
An object with __anext__(), for use with anext() or async for.
Python Examples
Example 1 — Pull Items from an Async Generator
Get an async iterator, await two items manually, then let async for take the rest.
python
import asyncio
async def ticker(limit):
for i in range(limit):
await asyncio.sleep(0)
yield i
async def main():
it = aiter(ticker(3))
print(await anext(it))
print(await anext(it))
async for value in it:
print("rest:", value)
asyncio.run(main())
Output
0
1
rest: 2
How It Works
Async generator.ticker() uses yield inside async def, so calling it returns an async iterable.
aiter, then anext.aiter() gives the iterator and each await anext(it) fetches one value.
Continue with async for. The loop resumes from where the manual calls stopped, so only 2 is left.
Event loop.asyncio.run(main()) creates the loop, runs main(), and closes it.
Example 2 — Implement __aiter__ and __anext__
Write an async iterable class and check what aiter() returns for it.
python
import asyncio
class AsyncCountdown:
def __init__(self, start):
self.start = start
def __aiter__(self):
self.current = self.start
return self
async def __anext__(self):
if self.current <= 0:
raise StopAsyncIteration
await asyncio.sleep(0)
self.current -= 1
return self.current + 1
async def main():
countdown = AsyncCountdown(3)
iterator = aiter(countdown)
print(iterator is countdown)
print([n async for n in iterator])
asyncio.run(main())
Output
True
[3, 2, 1]
How It Works
__aiter__ is called.aiter(countdown) runs __aiter__(), which resets the counter and returns the object itself.
__anext__ is a coroutine. Each step awaits, then returns the current number.
End signal. Raising StopAsyncIteration tells async loops and comprehensions to stop.
Async comprehension.[n async for n in iterator] collects 3, 2, 1 inside main().
Example 3 — Async Iterables vs Regular Iterables
See that a list is rejected, while an async generator works with aiter().
python
import asyncio
async def letters():
for ch in "ab":
yield ch
async def main():
try:
aiter([1, 2, 3])
except TypeError:
print("a list is not an async iterable")
collected = []
async for ch in aiter(letters()):
collected.append(ch.upper())
print(collected)
print(hasattr(letters(), "__aiter__"), hasattr([], "__aiter__"))
asyncio.run(main())
Output
a list is not an async iterable
['A', 'B']
True False
How It Works
Lists are synchronous. A list has __iter__ but no __aiter__, so aiter() raises TypeError.
Explicit aiter() in a loop.async for ch in aiter(...) works, though async for ch in letters() is equivalent.
Duck typing.hasattr(obj, "__aiter__") shows which objects qualify.
Convert sync data. To feed a list into async code, wrap it in a small async generator like letters().
Frequently Asked Questions
Python 3.10, together with anext().
iter() works with regular iterables and next(). aiter() works with async iterables and await anext().
No. async for calls __aiter__ automatically. aiter() is for stepping through an async iterator by hand.
No. aiter() returns the iterator directly. You await anext() to get each item.
Call obj.__aiter__() and await it.__anext__() directly; they do the same thing.