next()

Advance an iterator by one — with an optional default to fall back on when the iterator is exhausted.

Built-in functionPython 2.6+
Common call
first = next(iter(items), None)
Returns
the next item, or default if given and iterator is exhausted
Replaces
try/except StopIteration around iterator.__next__()
Watch out
without a default, StopIteration is raised on exhaustion — catch or default it
next(iterator[, default])
→ Any

Parameters

NameTypeRequiredDescription
iteratoriteratoryesAn iterator object (from iter(), map, filter, a generator, ...). Iterables that are NOT iterators (like plain lists) raise TypeError.
defaultAnynoValue returned when the iterator is exhausted, instead of raising StopIteration. A sentinel object is a common choice.

Return value

Any — The next item from the iterator. If the iterator is exhausted: raises StopIteration when default is omitted, or returns default when supplied.

Common patterns

Get the first item with a default
The idiomatic "first item if any" pattern.
first = next(iter(items), None)
Find the first matching item
Combine with a generator expression for lazy find.
match = next((x for x in items if pred(x)), None)
Consume one to skip
Skip a known header row or magic byte.
it = iter(lines)
next(it, None)   # discard header
for line in it:
    parse(line)
Detect emptiness with a sentinel
A distinct sentinel object avoids ambiguity when None or "" is a legitimate value.
_missing = object()
first = next(iter(items), _missing)
if first is _missing:
    raise ValueError("no items")

Examples

1. First of a list
next(iter([1, 2, 3]))
Returns
1
2. Iterator preserved
it = iter([1,2]) next(it); next(it)
Returns
2 # second call
3. Exhausted with default
next(iter([]), "done")
Returns
"done"
4. Empty raises
next(iter([]))
Returns
StopIteration
5. First matching
next((x for x in [1,2,3] if x > 1), None)
Returns
2
6. No match with default
next((x for x in [1,2,3] if x > 10), None)
Returns
None

Pitfalls

1. Raises StopIteration on empty — without a default
The single most common next() surprise. In Python 3.7+, StopIteration inside a generator becomes RuntimeError (PEP 479), so a bare next() in a comprehension is now dangerous.
Bare next raises
next(iter([]))
StopIteration
Provide a default
next(iter([]), None)
None
2. Only ITERATORS, not iterables
A list is not an iterator; you cannot call next() on a plain list. You need to wrap in iter() first (or use a generator, map, filter, etc.).
List rejected
next([1, 2, 3])
TypeError: 'list' object is not an iterator
Wrap in iter
next(iter([1, 2, 3]))
1
3. The iterator ADVANCES — repeated calls give different values
next() is stateful. Each call moves the cursor. Calling next() twice from the same iterator yields the first and second items, not the first twice.
Assumed idempotent
it = iter([1, 2, 3])
next(it); next(it); next(it)
1, 2, 3
Iterator state matters
it = iter([1, 2, 3])
[next(it), next(it), next(it)]
[1, 2, 3]
4. PEP 479: StopIteration inside a generator becomes RuntimeError
Since Python 3.7, if a StopIteration leaks out of a generator (from a bare next() inside it), Python raises RuntimeError. Always provide a default for next() inside generator expressions.
Leaks in generator
g = (next(it) for it in iters)   # some it may be empty
RuntimeError
Default it
g = (next(it, None) for it in iters)
clean

When to use

Use it
  • Getting the FIRST item of an iterator — always with a default
  • Finding the first matching item via a generator expression
  • Consuming a header or sentinel before a for-loop
  • Peeking at state during manual iteration
Reach for something else
  • Iterating a whole sequence → use a for-loop instead
  • You need a list of all items → use list()
  • You need N items → itertools.islice
  • Bare next() inside a generator — PEP 479 makes this a RuntimeError

Notes

Complexity
O(1) per call — plus whatever the iterator does under the hood
Return
The next item, or the default value
CPython impl
Python/bltinmodule.c :: builtin_next — calls the iterator's tp_iternext slot
Memory
No allocation beyond the returned value
Thread-safe
Not safe under concurrent advancement of the same iterator

FAQ

Because a list is an ITERABLE, not an ITERATOR. next() only works on iterators. Wrap the list in iter() first: `next(iter([1, 2, 3]))`.

History

2.6
next() builtin introduced. Previously you called iterator.next() directly.
3.0
iterator.next() renamed to iterator.__next__(); next() is now the only public interface.
3.7
PEP 479 finalized — StopIteration leaking from a generator becomes RuntimeError.