Python

Python itertools — Count, Chain, Group, and Combine

A loop often spends most of its lines building the next value, joining two lists, or tracking a running total. The itertools module in the standard library holds small tools for those jobs. Each tool takes one or more iterables and returns an iterator that makes values one at a time, only when asked. This guide builds the module one piece at a time: endless streams first, then joining and filtering, running totals, grouping, pairings, slicing, and the traps that catch a first user. Each step is a small working program with the exact output it prints.

Written November 13, 2026 · Tested with Python 3.12.3 · 12 min read

By the end of this guide
  • The main program: endless streams, cut short
  • Joining and filtering streams
  • Running totals with accumulate, pairings with product
  • Grouping sorted data with groupby

Written November 13, 2026

Tested with Python 3.12.3

What this guide is

An iterable is anything a loop can walk through, such as a list, a string, or a file. An iterator is the object that hands out the values one at a time. The itertools tools return iterators, so they make no list and hold no results until code asks for the next value. That lazy shape is why a tool can describe an endless stream without running forever: the stream exists only as a rule for the next value, and the caller decides when to stop asking. Most programs in this guide end by turning an iterator into a list, because a list shows every value the iterator would have given.

The main program: endless streams, cut short

Three tools make streams with no end. The count tool starts at a number and adds a step each time. The cycle tool walks through an iterable and starts again at the top. The repeat tool gives the same value again and again. None of them can go into a list call on its own, because the list would never fill. The islice tool takes a set number of values and then stops, which makes an endless stream safe to print:

Python
import itertools

counter = itertools.count(10, 5)
print([next(counter) for _ in range(4)])
print(list(itertools.islice(itertools.cycle("ABC"), 7)))
print(list(itertools.repeat("tick", 3)))
print(list(itertools.islice(itertools.count(1), 3)))

The exact output:

Config
[10, 15, 20, 25]
['A', 'B', 'C', 'A', 'B', 'C', 'A']
['tick', 'tick', 'tick']
[1, 2, 3]

The count stream began at 10 and stepped by 5, and four next calls pulled the first four values. The cycle stream gave the letters of ABC twice and then began a third pass, stopped at seven values by islice. The repeat call carried a count of its own, so it ended after three values without help. A repeat call with no count never ends, and needs islice or a loop that stops on its own.

Joining and filtering streams

The chain tool reads one iterable to the end, then the next, as if they were one long iterable. Its from_iterable form takes a single iterable of iterables instead, which fits a list of lists. The compress tool pairs two streams and keeps a value only where the paired selector is true. The dropwhile tool skips values while a test passes and then gives the rest, and takewhile does the reverse, giving values while the test passes and stopping at the first failure:

Python
import itertools

print(list(itertools.chain([1, 2], "ab", (9,))))
print(list(itertools.chain.from_iterable([[1, 2], [3], []])))
print(list(itertools.compress("ABCDEF", [1, 0, 1, 0, 1, 0])))
numbers = [1, 3, 5, 8, 10]
print(list(itertools.dropwhile(lambda x: x < 6, numbers)))
print(list(itertools.takewhile(lambda x: x < 6, numbers)))

The exact output:

Config
[1, 2, 'a', 'b', 9]
[1, 2, 3]
['A', 'C', 'E']
[8, 10]
[1, 3, 5]

The chain output kept the order of its inputs: the list, then the letters of the string, then the tuple value. The compress output kept A, C, and E, the letters whose selector was 1. The dropwhile call skipped 1, 3, and 5, then gave 8 and 10 without testing them further. The takewhile call gave the same first three values and stopped for good at 8, so a later small value would never appear. That one-way behavior is the point of both tools, and it differs from a filter, which tests every value.

Running totals with accumulate, pairings with product

The accumulate tool gives a running result. It starts with the first value, then folds each new value into the total with a function. With no function it adds, so the output is a running sum. Passing the mul function from the operator module gives a running product, and passing max gives the largest value seen so far. The product tool is a different tool with a close name: it pairs every value from one iterable with every value from another, the way nested loops do:

Python
import itertools, operator

print(list(itertools.accumulate([1, 2, 3, 4])))
print(list(itertools.accumulate([1, 2, 3, 4], operator.mul)))
print(list(itertools.accumulate([3, 1, 4, 1, 5], max)))
print(list(itertools.product("AB", "xy")))
print(list(itertools.product([1, 2], repeat=2)))

The exact output:

Config
[1, 3, 6, 10]
[1, 2, 6, 24]
[3, 3, 4, 4, 5]
[('A', 'x'), ('A', 'y'), ('B', 'x'), ('B', 'y')]
[(1, 1), (1, 2), (2, 1), (2, 2)]

The running sum ended at 10, the total of the four values, and each step showed the sum up to that point. The running product ended at 24, and the max form never went down: 3 held until 4 arrived, and 5 closed the list. The product output paired A and B with x and y in order, four pairs from two pairs of inputs. The repeat argument pairs an iterable with itself, so the second product call gave the four pairs of 1 and 2. The size of a product grows fast: each added input multiplies the count of pairs, so a product over long inputs makes a long stream.

Grouping sorted data with groupby

The groupby tool gathers runs of values that share a key. It gives back pairs of the key and a group iterator, and the group holds the values from one run. The data must already be in key order, because groupby only looks at neighbors: when the key changes, a new group starts. This program groups words by their first letter, then groups pairs by their first item and pulls the second item out of each group:

Python
import itertools

words = ["ant", "ape", "bat", "bee", "cat"]
for key, group in itertools.groupby(words, key=lambda w: w[0]):
    print(key, list(group))
data = [("a", 1), ("a", 2), ("b", 3), ("b", 4), ("c", 5)]
for key, group in itertools.groupby(data, key=lambda pair: pair[0]):
    print(key, [value for _, value in group])

The exact output:

Output
a ['ant', 'ape']
b ['bat', 'bee']
c ['cat']
a [1, 2]
b [3, 4]
c [5]

The words were in first-letter order, so each letter made one group. The group value is itself an iterator, and turning it into a list inside the loop is what captures its values. A group must be read before the loop moves on: once groupby steps to the next key, the old group gives nothing. Sorting first is the normal shape of this tool, most often with the same key function passed to both the sort and the groupby call.

Counting choices: permutations and combinations

Three tools list the ways to pick from a set. The combinations tool picks a set number of values in input order, with no value used twice and no repeats in a different order. The permutations tool treats order as part of the pick, so AB and BA both appear. The combinations_with_replacement tool lets a value appear more than once in one pick. Each tool gives tuples, and the counts grow fast:

Python
import itertools

print(list(itertools.combinations("ABC", 2)))
print(list(itertools.permutations("ABC", 2)))
print(list(itertools.combinations_with_replacement("AB", 2)))
print(len(list(itertools.permutations("ABCD"))))
print(len(list(itertools.combinations("ABCDE", 3))))

The exact output:

Config
[('A', 'B'), ('A', 'C'), ('B', 'C')]
[('A', 'B'), ('A', 'C'), ('B', 'A'), ('B', 'C'), ('C', 'A'), ('C', 'B')]
[('A', 'A'), ('A', 'B'), ('B', 'B')]
24
10

Three letters gave three pairs as combinations and six as permutations, because each combination in a new order counts again. A full permutation of four letters gave 24 tuples: 4 choices for the first place, then 3, then 2, then 1, multiplied together. Picking 3 from 5 as combinations gave 10. These tools suit small inputs, such as testing every order of a few steps or every pair from a short list. On a long input the stream itself becomes the problem, long before any single value is slow.

Slicing, pairing by position, and splitting a stream

The islice tool works on any iterator the way a slice works on a list, with a start, a stop, and a step, but it cannot go backward or use a negative index, because an iterator has no stored values to count from the end. The zip_longest tool pairs values by position like the built-in zip, but it keeps going until the longest input ends and fills the gaps with a fill value. The starmap tool calls a function with each tuple in a stream as its arguments. The tee tool splits one iterator into two that can be read on their own:

Python
import itertools

print(list(itertools.islice(range(100), 5)))
print(list(itertools.islice(range(100), 2, 8, 2)))
print(list(itertools.zip_longest("AB", "wxyz", fillvalue="-")))
print(list(itertools.starmap(pow, [(2, 3), (3, 2), (10, 2)])))
first, second = itertools.tee(iter([10, 20, 30]), 2)
print(list(first))
print(list(second))

The exact output:

Config
[0, 1, 2, 3, 4]
[2, 4, 6]
[('A', 'w'), ('B', 'x'), ('-', 'y'), ('-', 'z')]
[8, 9, 100]
[10, 20, 30]
[10, 20, 30]

The first islice call took five values from a range of a hundred without building the rest as a new list. The second started at 2 and stepped by 2 up to 8. The zip_longest output shows the fill value in the first slot once the short input ran out. The starmap call raised 2 to the third power, 3 to the second, and 10 to the second, reading each pair as the two arguments of pow. The tee call let both readers see all three values, which a single shared iterator cannot do, as the traps section shows.

Three traps a first user meets

Trap
The groupby sorting trap is the most common. When the input is not in key order, the same key opens a new group each time it comes back, so one letter can head several groups and a count by key comes out split. The second trap is the used-up iterator: an iterator gives each value once, and a second pass gives nothing, with no error. The third point is a habit rather than an error: an endless stream is safe only behind a tool or a loop that stops, such as islice:
Python
import itertools

words = ["ant", "bat", "ape", "bee"]
print([(key, list(group)) for key, group in itertools.groupby(words, key=lambda w: w[0])])
numbers = iter([1, 2, 3])
print(list(numbers))
print(list(numbers))
print(list(itertools.islice(itertools.count(100), 3)))
print(len(list(itertools.permutations(range(5)))))

The exact output:

Config
[('a', ['ant']), ('b', ['bat']), ('a', ['ape']), ('b', ['bee'])]
[1, 2, 3]
[]
[100, 101, 102]
120

The unsorted words made four groups for two letters, with a and b each appearing twice. Sorting the same words by their first letter would have made two groups. The second list call on the used-up iterator printed an empty list, not the values again. The count stream starting at 100 stopped after three values because islice asked for three. The last line counts the permutations of five values: 120, the product of 5 down to 1, which is why a permutation stream over even ten values runs into millions.

Which tool for which job

Job Tool Why
Numbering or stepping through a range with a set step count with islice The stream starts and steps as told, and islice sets where it stops
Repeating a fixed pattern cycle The tool walks the pattern and starts again at the top on its own
Joining several iterables end to end chain One stream reads each input in turn, with no joined list built
Keeping values where a paired selector is true compress The selector stream decides value by value what survives
A running total, product, or best-so-far accumulate Each output folds the next input into the result so far
Grouping rows that share a key groupby, after sorting by that key Neighbor runs with the same key become one group
Every pairing of two sets product The pair order matches nested loops over the inputs
Every order or pick from a small set permutations or combinations Order counts in permutations and does not in combinations
Taking a set number of values from any iterator islice It stops after the count, even on an endless stream
Reading one iterator in two places tee Each reader gets the full stream on its own schedule

Checklist

  • Before putting an endless stream into a list call, place islice or a stopping loop between them.
  • Before calling groupby, sort the data by the same key the groupby call will use.
  • Before moving past a groupby group, read it into a list or use its values; the next key closes it.
  • Before reading an iterator a second time, build it again or split it with tee; a used-up iterator gives nothing.
  • Before running permutations or product on a new input, count the results on paper; the count multiplies fast.
  • Before building a running total by hand, reach for accumulate and pass the fold function the job needs.

Sources

  • Python Standard Library, itertools — count, cycle, repeat, chain, compress, dropwhile, takewhile, accumulate, product, groupby, islice, permutations, combinations, combinations_with_replacement, zip_longest, starmap, and tee, with their arguments and behavior.
  • Python Standard Library, operator — the mul function passed to accumulate for a running product, and the function forms of the standard operators.

Keep Exploring