Python aiter() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Python 3.10+

Definition

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 await anext() 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)
CallWhat it does
aiter(agen())An async iterator over an async generator.
await anext(aiter(x))The first item.
aiter(obj) is objOften 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

ParameterDescription
async_iterableRequired. An object with __aiter__(), such as an async generator.

Return Value

Return ValueDescription
async iteratorAn 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())

How It Works

  1. Async generator. ticker() uses yield inside async def, so calling it returns an async iterable.
  2. aiter, then anext. aiter() gives the iterator and each await anext(it) fetches one value.
  3. Continue with async for. The loop resumes from where the manual calls stopped, so only 2 is left.
  4. 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())

How It Works

  1. __aiter__ is called. aiter(countdown) runs __aiter__(), which resets the counter and returns the object itself.
  2. __anext__ is a coroutine. Each step awaits, then returns the current number.
  3. End signal. Raising StopAsyncIteration tells async loops and comprehensions to stop.
  4. 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())

How It Works

  1. Lists are synchronous. A list has __iter__ but no __aiter__, so aiter() raises TypeError.
  2. Explicit aiter() in a loop. async for ch in aiter(...) works, though async for ch in letters() is equivalent.
  3. Duck typing. hasattr(obj, "__aiter__") shows which objects qualify.
  4. 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.

Next: all()

True if every item is truthy (or the iterable is empty).

all() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful