Python Iterable Unpacking: Syntax and Pitfalls
Learn how Python iterable unpacking works: basic assignment, starred expressions, loops, function calls, dictionaries, and common pitfalls.

Python iterable unpacking lets you assign multiple variables from an iterable in a single statement. It is a core feature of the language that appears in everyday code, from swapping values to parsing function return values. This article covers the syntax, advanced patterns, and the edge cases that trip up even experienced developers.
The Basic Unpacking Syntax
The simplest form of unpacking assigns each element of an iterable to a variable in order. The number of variables must match the number of elements exactly.
coordinates = (10, 20)
x, y = coordinates
print(x, y) # 10 20This works with any iterable, not just tuples. Lists, strings, and generator objects are all valid sources.
first, second = [1, 2]
letter1, letter2 = "ab"For sized iterables (lists, tuples, strings, sets, and similar collections), if there are more elements than variables, Python raises a ValueError with the message "too many values to unpack". If there are fewer elements, it raises "not enough values to unpack". For a generator or another iterator without a known length, simple unpacking pulls only as many items as there are targets, so extra items do not cause an error; they remain available in the iterator. This strictness for sized collections is intentional: it forces you to handle the data shape explicitly rather than silently discarding values.
A common use is swapping variables without a temporary variable:
a, b = b, aThe right side is evaluated first, creating a tuple, then unpacked into the left side. This is idiomatic Python and avoids the need for a third variable.
Extended Unpacking with Starred Expressions
Python 3 introduced extended unpacking, which allows a single starred variable to absorb a sequence of elements. The starred expression can appear anywhere in the assignment target list.
first, *rest = [1, 2, 3, 4]
print(first) # 1
print(rest) # [2, 3, 4]*init, last = [1, 2, 3, 4]
print(init) # [1, 2, 3]
print(last) # 4The starred variable always receives a list, even if the source is a tuple or string. This is a deliberate design choice to keep the result uniform.
Extended unpacking is particularly useful when you need to separate the first element from the rest, or the last element from the prefix. It also works with any iterable, including generators, but note that it will consume the entire generator to build the list for the starred variable.
You can combine a starred expression with fixed variables, but only one starred expression is allowed per assignment. Attempting to use two will raise a SyntaxError.
Unpacking in Loops and Function Calls
Iterable unpacking shines in loops. Instead of indexing into a list of pairs, you can unpack each item directly in the for statement.
pairs = [(1, 'one'), (2, 'two')]
for number, name in pairs:
print(f"{number}: {name}")This works for any iterable of iterables, such as dictionaries when iterating over .items():
d = {'a': 1, 'b': 2}
for key, value in d.items():
print(key, value)Function calls also use unpacking. The * operator unpacks an iterable into positional arguments, and ** unpacks a mapping into keyword arguments.
def add(x, y):
return x + y
args = (3, 4)
print(add(*args)) # 7def greet(name, greeting="Hello"):
print(f"{greeting}, {name}")
kwargs = {"name": "Alice", "greeting": "Hi"}
greet(**kwargs) # Hi, AliceThese operators are distinct from the starred assignment unpacking, but they share the same mental model: expanding an iterable into individual components.
Unpacking Dictionaries and Mapping Types
Dictionaries are iterable over their keys, so unpacking a dictionary directly gives keys, not key-value pairs.
d = {'x': 1, 'y': 2}
a, b = d
print(a, b) # x yTo unpack keys and values together, use .items():
(k1, v1), (k2, v2) = d.items()But that is brittle because it assumes exactly two items. A more robust approach is to loop over .items().
In function calls, ** unpacks a dictionary into keyword arguments. This is common when passing configuration dictionaries to functions.
config = {'host': 'localhost', 'port': 8080}
connect(**config)Python 3.5 also introduced dictionary unpacking in dictionary literals, allowing you to merge mappings:
base = {'a': 1}
extra = {'b': 2}
merged = {**base, **extra}This is a concise way to combine dictionaries, though it creates a new dictionary and does not mutate the originals.
Common Mistakes and Edge Cases
One frequent error is assuming that unpacking a string gives individual characters as separate variables. It does, but only if the string length matches the number of variables. If you need to split on a delimiter, use .split() instead.
Another pitfall is unpacking a generator that is infinite or very large. When a starred expression is present, Python will consume the entire generator to build the list, which can exhaust memory. For example:
first, *rest = generate_numbers() # consumes allIf you only need a few elements, consider using itertools.islice to avoid materializing the whole sequence.
Nested unpacking is allowed but can become hard to read. For instance:
(a, (b, c)) = (1, (2, 3))This works, but if the nested structure is complex, it may be clearer to unpack in steps.
A subtle bug occurs when you use a starred expression in a loop that expects a fixed number of elements. The starred variable will capture all remaining items, which may hide data shape issues. Always verify that the iterable has the expected structure.
Runtime and Memory Considerations
For simple assignment without a starred expression, Python evaluates the right-hand side as an iterable and attempts to unpack exactly as many items as there are targets. The cost is proportional to the number of targets, not to the length of the whole iterable, and is negligible for typical sizes.
Extended unpacking with a starred variable has different memory behavior. The starred variable always becomes a list, so if the source is a large iterable, that list occupies memory proportional to its length. This can contradict the lazy nature of generators: if you unpack a generator that yields millions of items with a starred expression, Python forces full evaluation, which can cause a MemoryError.
For performance-critical code, consider whether a large iterable needs to be unpacked at all. If you only need a few items, use next() or itertools.islice on an iterator instead of unpacking with a star.
Unpacking in a for loop does not add a separate tuple-construction step beyond what the iterable already produces during iteration. Microbenchmarks that compare unpacking with indexing are environment-specific and are unlikely to matter compared with the work done inside the loop body.
When to Use Unpacking vs. Indexing
Choosing between unpacking and indexing depends on the context and the readability you need.
Use unpacking when:
- The structure of the iterable is fixed and known in advance.
- You want to give meaningful names to each element.
- You are iterating over a collection of pairs or tuples.
- You need to swap values or assign multiple variables at once.
Use indexing when:
- You only need one or two elements from a larger collection.
- The iterable is a list or tuple with a variable length, and you want to access by position.
- You are working with a sequence where the position is semantically meaningful (e.g.,
coordinates[0]).
Indexing is also more appropriate when the iterable is a string and you want to access characters by position, though unpacking a string into a fixed number of variables is possible if the length is guaranteed.
In function calls, * and ** are the standard way to forward an argument collection, and they are preferable to manually indexing into a list of arguments because they preserve the function signature.
A practical rule: if unpacking makes the code read like the data structure it represents, use it. If it obscures the relationship between positions and meaning, stick with indexing or explicit variable assignment.
Unpacking is not a performance tool; it is a readability tool. The Python interpreter optimizes simple unpacking well, but the real benefit is that it communicates intent clearly and reduces the chance of off-by-one errors when accessing elements by index.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.