How Does Tuple Unpacking Work?

Unpacking lets you take a sequence of values and bind them to several names in one statement.

# Simple swap
a, b = 1, 2
a, b = b, a
print(a, b)                        # 2 1

# Nested unpacking
first, (second, third) = 1, (2, 3)
print(first, second, third)        # 1 2 3

# Unpacking in a loop
pairs = [(1, "a"), (2, "b")]
for number, letter in pairs:
    print(number, letter)

# Unpacking a returned tuple
def split(value):
    return value // 2, value % 2


whole, remainder = split(17)
print(whole, remainder)            # 8 1

# Starred unpacking
head, *rest = [1, 2, 3, 4]
print(head, rest)                  # 1 [2, 3, 4]

Every one of these is the same underlying operation: the right-hand side is evaluated to a sequence, and its elements are distributed to the targets on the left. The swap works because the right side is fully evaluated before any name is rebound. The nested form works because the parenthesised target is itself a pattern, so the inner tuple is unpacked in turn.

The starred form absorbs the remaining elements into a list. It always binds exactly one name, and the list it produces is always a list even when the rest is empty, so head, *rest = [1] gives rest as an empty list rather than None.

Unpacking also works on any iterable, not just tuples, which is why you can write a, b = some_generator and a, b = a_dict — the latter unpacks the keys in insertion order. And because it works in a for loop, iterating over a list of pairs is written as for key, value in pairs without any indexing.

Unpacking is handled by the bytecode, not by a generic loop. When the interpreter sees an assignment whose left-hand side is a tuple of names, it compiles it to a special sequence of instructions: UNPACK_SEQUENCE for a known number of targets, or UNPACK_EX for the starred form. UNPACK_SEQUENCE pops the right-hand value, checks that it is iterable, and pushes its elements onto the stack in reverse order. The stores then bind each element to its target name. Because the length is fixed at compile time, the whole thing is a handful of bytecode instructions with no Python-level loop.

That is why unpacking is fast, and also why the length must match exactly. If the right-hand side has fewer elements than there are targets, or more, the interpreter raises a ValueError. The message names both counts — for example, too many values to unpack (expected 2) or not enough values to unpack (expected 3, got 2) — so the error tells you exactly what went wrong.

Two details. The starred form relaxes the count, because UNPACK_EX knows how many elements to take for the starred target and puts the remainder into a list; it always needs at least the number of fixed targets. And unpacking works with any iterable, not only sequences, so if the right-hand side is a generator it is consumed into a sequence first, and if it is a dict it yields its keys.

One practical consequence worth mentioning: because the count must match, unpacking is a way of asserting the shape of data. If a function returns a two-tuple and you unpack it into two names, the code fails loudly at the call site if the return shape changes, instead of silently handing you the wrong field.