Python anext() Function

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

Definition

In Python 3.10 and newer, anext(async_iterator) is the async version of next(). It returns an awaitable; await anext(it) produces the next item. When the iterator is exhausted, awaiting it raises StopAsyncIteration.

Like next(), it accepts a default: await anext(it, None) returns None at the end instead of raising. Get the iterator with aiter() or use an async generator object directly, and run everything inside asyncio.run().

anext() 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, use await it.__anext__() instead.

Syntax

Await the call inside an async def function.

python
async def main():
    item = await anext(async_iterator)
    item = await anext(async_iterator, default)
CallWhat it does
await anext(agen)The next item.
await anext(agen, None)None when exhausted.
anext(agen)An awaitable; nothing runs until it is awaited.
await anext(aiter(x))The first item of an async iterable.

Forgetting await is the most common bug: you get an awaitable object instead of the item.

Library declarations
python
anext(async_iterator, /)
anext(async_iterator, default, /)
# returns an awaitable; new in Python 3.10

Parameters

ParameterDescription
async_iteratorRequired. An object with __anext__(), such as an async generator.
defaultOptional. Returned instead of raising StopAsyncIteration.

Return Value

Return ValueDescription
awaitableAwaiting it gives the next item, or default when the iterator is exhausted.

Python Examples

Example 1 — Await Items and Fall Back to a Default

Read two values from an async generator, then get the default at the end.

python
import asyncio


async def numbers():
    yield 1
    yield 2


async def main():
    it = numbers()
    print(await anext(it))
    print(await anext(it))
    print(await anext(it, "no more"))


asyncio.run(main())

How It Works

  1. Async generators are async iterators. numbers() can be passed straight to anext().
  2. Await each step. await anext(it) resumes the generator until its next yield.
  3. Default at the end. After two values, the third call returns "no more" instead of raising.
  4. One entry point. asyncio.run(main()) runs the whole coroutine.

Example 2 — Handle StopAsyncIteration

Read the only message of an async inbox and catch the end-of-stream exception.

python
import asyncio


async def one_message():
    yield "hello"


async def main():
    inbox = one_message()
    print(await anext(inbox))
    try:
        await anext(inbox)
    except StopAsyncIteration:
        print("StopAsyncIteration: inbox is empty")


asyncio.run(main())

How It Works

  1. A single item. The generator yields "hello" once.
  2. No default. The second await anext(inbox) has nothing to return.
  3. Async end signal. Async iterators raise StopAsyncIteration, not StopIteration.
  4. Caught like any error. A normal try/except handles it inside the coroutine.

Example 3 — First Matching Reading from an Async Stream

Use an async generator expression with anext(..., None), and see that anext() returns an awaitable.

python
import asyncio


async def sensor_readings():
    for value in [17, 21, 24, 19]:
        await asyncio.sleep(0)
        yield value


async def first_above(limit):
    readings = (r async for r in sensor_readings() if r > limit)
    return await anext(readings, None)


async def main():
    print(await first_above(20))
    print(await first_above(30))
    pending = anext(sensor_readings())
    print(hasattr(pending, "__await__"))
    print(await pending)


asyncio.run(main())

How It Works

  1. Async filter. (r async for r in ... if r > limit) is an async generator expression.
  2. First match or None. 21 is the first reading above 20; nothing exceeds 30, so the default is returned.
  3. Awaitable first. Without await, anext() returns an object with __await__, not a number.
  4. Await later. Awaiting pending finally runs the generator and yields 17.

Frequently Asked Questions

Python 3.10, together with aiter().
next() returns the item directly from a regular iterator. anext() returns an awaitable for an async iterator; you must await it.
StopAsyncIteration, unless you pass a default value.
You forgot await. Write item = await anext(it).
No. Await it inside an async def function that runs in an event loop, for example via asyncio.run().

Next: any()

True if at least one item is truthy.

any() →

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.

10 people found this page helpful