Quick answer: Python sequence unpacking requires the number of target names to match the values produced by the iterable. Count the right-hand side, use a starred target when the remainder has a defined meaning, and remember that dictionary iteration yields keys by default.
ValueError: too many values to unpack (expected 2) happens when Python tries to assign more values than there are target variables. If the right side has three values and the left side has two names, Python does not know where the extra value should go.
This error is common with tuples, lists, function returns, loops, and dictionaries. The fix is to make the number of variables match the number of values, use a starred variable for extras, or unpack the correct object.
The important thing is to inspect the shape of the data before changing the assignment. A quick print(value) or len(value) often reveals whether you are receiving two values, three values, or a nested structure. Once you know the real shape, the fix is usually small.
Do not assume the phrase “expected 2” means Python always wanted two values. It means your code wrote two target variables in that assignment. If you write three target variables, Python will expect three values instead.
Match the Number of Variables
Python assignment unpacking expects the number of names on the left to match the number of values on the right, unless you use starred unpacking.
values = (1, 2, 3)
first, second, third = values
print(first, second, third)
If you only write first, second = values, Python raises the error because there are three values but only two target names. The official Python docs cover this under assignment statements. Matching counts is the cleanest fix when every returned value is meaningful.
Use Starred Unpacking for Extra Values
Use a starred variable when you need the first value, last value, or a few named values while collecting the rest.
values = (1, 2, 3, 4)
first, *middle, last = values
print(first)
print(middle)
print(last)
The starred name receives a list of the extra values. This is cleaner than guessing how many values will appear. For more examples, see unpack tuple in Python. Use a descriptive name like remaining or extras when the collected values matter.
Fix Loops Over Lists of Tuples
This error often appears in for loops when each item has more fields than the loop expects.
rows = [
("Ada", 91, "A"),
("Linus", 84, "B"),
]
for name, score, grade in rows:
print(name, score, grade)
If the loop used for name, score in rows, each three-item tuple would be too large for two variables. When the row structure is uncertain, print the first row before unpacking it. The iterate through a list in Python guide covers loop patterns. This issue is common with CSV rows and API results where a new field was added.
Unpack Dictionary Items Correctly
Looping over a dictionary directly gives keys, not key-value pairs. Use .items() when you want two values in each iteration.
scores = {"Ada": 91, "Linus": 84}
for name, score in scores.items():
print(name, score)
If your keys are strings, writing for name, score in scores may try to unpack characters from each key. Use .items() for key-value pairs and .values() when only values are needed. This is one of the fastest fixes to check when the error appears inside a dictionary loop.
Check Function Return Values
Function return values can also cause this error. Make sure the caller expects the same number of values that the function returns.
def user_summary():
return "Ada", 91, "active"
name, score, status = user_summary()
print(name, score, status)
If the caller only expects two variables, either change the function return shape or collect the extra value with a starred variable. Be explicit because return shapes are part of a function’s contract. When you change a function to return more values, update every caller that unpacks the result.
Handle Split Strings Carefully
String splitting can produce more parts than expected. Limit the split when only two pieces are needed.
line = "name=Ada=active"
key, value = line.split("=", 1)
print(key)
print(value)
The second argument to split() limits the number of splits. Without it, the example would produce three parts. If you need to convert tuple data to text later, see tuple to string in Python. For user input, handle missing separators separately so you do not trade one error for another.
Debug the Error Quickly
When the source is unclear, print the value and check its length before unpacking. For nested lists or arrays, inspect shape as well; list shape in Python explains that idea. For object dictionaries, Python vars() can help inspect available fields.
Do not hide this error with a broad except block. It usually means your data shape is different from what the code expects. Fixing the assignment or input shape is better than ignoring the exception. A clear unpacking statement is also documentation for the structure your code expects.
References
- Python reference: assignment statements
- Python tutorial: tuples and sequences
- Python tutorial: errors and exceptions
Match The Target Shape
When Python evaluates left, right = values, it asks the iterable for values and assigns them positionally. A three-item iterable cannot fit two ordinary targets, and a one-item iterable cannot fill two. Inspect the data contract rather than adding a random variable just to silence the error.
pair = ("Ada", 36)
name, age = pair
print(name, age)
values = ("Ada", 36, "Python")
first, second, *rest = values
print(first, second, rest)
Use Starred Unpacking Deliberately
One starred target collects zero or more values into a list. It is useful for a header plus remaining columns, but it can hide a malformed record if the remainder should have exactly one value. Validate the collected length when the input format is strict.
header, *columns = ["id", "name", "score"]
if len(columns) != 2:
raise ValueError("expected exactly two columns")
print(header, columns)Know What The Iterable Produces
Iterating over a dictionary produces keys, not key-value pairs. For pairs, use data.items(); for a string, unpacking yields characters; for a database row or API response, inspect its documented sequence shape. The fix depends on the object, not just the exception text.
data = {"name": "Ada", "age": 36}
for key, value in data.items():
print(key, value)
letters = ["a", "b"]
a, b = lettersPython’s sequence-unpacking rules describe why the target count and iterable shape must agree.
For nearby data-shape fixes, compare dictionary iteration, list length, and two-dimensional list structure.
Frequently Asked Questions
Why does Python say too many values to unpack?
The iterable on the right produces more values than the assignment targets on the left can receive.
How do I unpack only the first value?
Use a starred target such as first, *rest = values when collecting the remaining values is intentional.
How do I unpack dictionary items?
Iterating over a dictionary yields keys; use for key, value in data.items() when each item is a key-value pair.
What is the difference from not enough values to unpack?
Too many values means the right side produces more values than targets, while not enough values means it produces fewer.
This was very helpful, thank you!