Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python itertools combinations: Syntax and Use Cases

Learn how to use itertools.combinations in Python: syntax, code examples, practical use cases, and performance tradeoffs.

~5 min readPython
#itertools#combinations#python#algorithms
Illustration of Python itertools.combinations generating unique pairs from a list

To generate fixed-length combinations without replacement from a Python iterable, use itertools.combinations. For an iterable of n elements, it yields n! / (r! * (n-r)!) tuples, each of length r. This is the standard way to enumerate subsets of a fixed size without writing nested loops.

The Signature and Return Behavior

itertools.combinations(iterable, r) takes two arguments: an iterable and the length of each output tuple. It returns an iterator that produces tuples in lexicographic order according to the order of the input. It does not build a list of all combinations at once; it yields them one at a time, which is useful when working with large inputs.

python
from itertools import combinations items = ['a', 'b', 'c'] for combo in combinations(items, 2): print(combo)

This prints ('a', 'b'), ('a', 'c'), and ('b', 'c'). The order follows the input sequence: elements within a tuple appear in the same relative order as in the original iterable, and tuples are emitted in lexicographic order.

Basic Usage with Numbers and Strings

The function works with any iterable, including lists, tuples, strings, and generators. When the input is a string, combinations are tuples of characters, not strings. This is a common point of confusion for developers expecting substrings.

python
from itertools import combinations word = 'abc' for combo in combinations(word, 2): print(combo) # ('a', 'b'), ('a', 'c'), ('b', 'c')

To get string results, you can join each tuple: ''.join(combo). For numeric data, combinations are tuples of numbers, which you can process directly in calculations.

Combinations vs. Permutations vs. Combinations With Replacement

itertools provides three related functions: combinations, permutations, and combinations_with_replacement. The key difference is whether order matters and whether elements can repeat.

  • combinations ignores order and does not repeat elements. ('a', 'b') is the same as ('b', 'a') and only one is emitted.
  • permutations treats order as significant, so both ('a', 'b') and ('b', 'a') are emitted.
  • combinations_with_replacement allows elements to repeat, so ('a', 'a') is a valid output.

Choosing the right function depends on the problem domain. For example, if you are selecting a committee from a group, order does not matter, so combinations is correct. If you are generating all possible two-character codes where order matters, use permutations. If repetition is allowed in the selection, use combinations_with_replacement.

Performance and Memory Considerations

The number of combinations can grow very quickly. For a list of 20 elements, combinations(items, 10) produces 184,756 tuples. For 30 elements, combinations(items, 10) produces 30,045,015 tuples, and combinations(items, 15) produces 155,117,520. Because the function returns an iterator, it does not store every output combination; memory use is proportional to the input size, not the number of combinations.

When you need to process combinations, avoid converting the iterator to a list unless you genuinely need all combinations at once. Iterating directly over the iterator keeps working memory low and allows you to stop early if you find what you need.

python
from itertools import combinations large_input = range(30) for combo in combinations(large_input, 10): # process each combo if some_condition(combo): break

This pattern is efficient because it does not build the full list of combinations in memory.

Practical Use Cases: Feature Engineering and Data Analysis

A common real-world use of itertools.combinations is generating feature pairs for machine learning models. For example, if you have a set of numeric features, you might want to create interaction terms for every pair. Instead of writing nested loops, you can iterate over combinations of feature indices.

python
from itertools import combinations feature_names = ['age', 'income', 'score'] for i, j in combinations(range(len(feature_names)), 2): print(f'{feature_names[i]} * {feature_names[j]}')

This produces age * income, age * score, and income * score. The same pattern applies to generating SQL join conditions, test case combinations, or any scenario where you need to enumerate all unordered pairs.

Common Pitfalls and Edge Cases

One frequent mistake is assuming that combinations returns an iterator that can be reused. Like all iterators, it is consumed after one pass. If you need to iterate twice, store the results in a list or recreate the iterator.

Another edge case is when r is larger than the iterable length. The function returns an empty iterator without raising an error. This silent behavior can hide bugs if you expect at least one combination.

python
from itertools import combinations items = [1, 2] print(list(combinations(items, 5))) # []

Also, the input iterable must be finite. Passing an infinite iterator, such as itertools.count(), will prevent the function from finishing because it needs the full set of elements to generate combinations.

When to Use Nested Loops Instead

While combinations is concise, there are cases where a nested loop is clearer. If you need to access the index of each element in the outer loop and perform custom logic that depends on the index, a nested loop may be more readable. For example, when you need to compare each element with every subsequent element and also know the positions, a double loop over range(len(items)) is straightforward.

However, for fixed-size combinations without index requirements, combinations is more readable and less error-prone. It also avoids the off-by-one errors that often appear in nested loops. The choice depends on whether the code's intent is better expressed as 'enumerate all pairs' or 'iterate with indices.'

Handling Large r Values and Performance Tradeoffs

When r is close to n, the number of combinations is the same as when r is close to 0. For example, combinations(items, 2) and combinations(items, n-2) produce the same count. If you need combinations of size n-1, you can often optimize by computing the complement. But itertools.combinations does not offer a direct way to generate complements; you would need to compute the missing element manually. This is a niche optimization that only matters when r is near n and the input is large enough to make the enumeration costly.

Another performance consideration is the overhead of tuple creation. Each combination is a new tuple, and for millions of combinations, this allocation can dominate runtime. If you only need to process the elements without storing them, consider using a loop that unpacks the tuple immediately to avoid holding references.

python
for a, b in combinations(items, 2): process(a, b)

This avoids creating an intermediate variable for the tuple, though the tuple itself is still created internally. For extreme performance requirements, you might implement a custom generator using arrays, but for most applications the overhead is acceptable.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.