Every item in a tuple has an index: its position number, starting at 0 for the first item. index(value) walks the tuple from the left and returns the index of the first item equal to value. The tuple itself is not changed; it cannot be, because tuples are immutable.
If no item matches, Python raises ValueError, the error it uses when a value has the right type but cannot be used, here because it is not in the tuple. Optional start and stop arguments let you search only part of the tuple, but the number you get back is still counted from the start of the whole tuple.
tuple.index() is an instance method of the built-in tuple type: call it on a tuple with dot notation, such as names.index("Chen"). No import is needed, and it works the same in all Python 3 versions. It is one of only two tuple methods; the other is count().
Syntax
Pass the value to find, and optionally where to start and where to stop looking.
Returns 2: the search begins at position 1, and the answer is counted from the front.
("x", "y").index("z")
Raises ValueError: "z" is not in the tuple.
start and stop are positional only: my_tuple.index(x, start=1) raises TypeError. Negative values count from the end, like slice bounds, and a stop past the end is fine. list.index() accepts the same three arguments.
Method signatures
python
tuple.index(value[, start[, stop]])
# returns: int, the position of the first item == value
# in my_tuple[start:stop], counted from index 0
# raises: ValueError when no item in that range matches
Parameters
Parameter
Description
value
Required. The value to find, compared with ==, so 2.0 finds an item 2.
start
Optional. The position where the search begins (default 0). A negative number counts from the end: -2 starts two items before the end.
stop
Optional. The search ends before this position (default: the end of the tuple). Needs start to be given too.
Return Value
Return Value
Description
int
The position of the first match, from 0 to len(my_tuple) - 1, always counted from the start of the tuple.
Python Examples
Example 1 — Find a Student's Score in a Parallel Tuple
Two tuples line up item by item: names and scores. The index of a name is also the index of that student's score.
Same position, two tuples. "Chen" is the third name, so index() returns 2, and scores[2] is Chen's score, 88.
Ties go to the earliest. Ben and Dina both scored 95, but index(95) stops at the first match, position 1, which belongs to Ben.
The last name. Dina sits at the end of a four-name tuple, so her index is 3, exactly len(names) minus 1.
Example 2 — Find Every Visit to the Depot on a Bus Route
The depot appears three times on the route. Use start to find the next visit after a match, and start plus stop to search a window.
python
route = ("Depot", "Mill", "Park", "Depot", "Lake", "Depot")
first = route.index("Depot")
second = route.index("Depot", first + 1)
print(first, second)
print(route.index("Depot", -2))
print(route.index("Lake", 2, 5))
Output
0 3
5
4
How It Works
Search again after a hit. The first "Depot" is at 0, so starting the next search at first + 1 skips it and finds the second visit at 3.
A negative start. -2 means "begin two items before the end", which is position 4 ("Lake"); the next "Depot" from there is the final stop, at 5.
A window with stop.index("Lake", 2, 5) looks only at positions 2, 3, and 4, finds "Lake" at 4, and reports 4, counted from the front of the route.
Example 3 — Look Up Drinks on a Fixed Cafe Menu
A menu of (name, price) pairs never changes, so it is a tuple. Find a drink by name, handle a missing one with try / except, and unpack the matching pair.
python
menu = (("tea", 2.5), ("coffee", 3.0), ("juice", 4.0))
items = tuple(name for name, _ in menu)
print(items)
for wanted in ("coffee", "soda"):
try:
pos = items.index(wanted)
except ValueError:
print(wanted, "is not on the menu")
else:
name, price = menu[pos]
print(f"{name} costs {price:.2f}")
Output
('tea', 'coffee', 'juice')
coffee costs 3.00
soda is not on the menu
How It Works
Names pulled out first. The generator expression unpacks each (name, price) pair, keeps only the name, and tuple() collects the three drink names in menu order.
try, except, else. "coffee" is found at 1, so the else block runs; "soda" is missing, so index() raises ValueError and the except block prints a friendly line instead of crashing.
Unpack the matching row. Position 1 in items is also position 1 in menu, and name, price = menu[pos] splits that pair into two variables for the f-string.
Frequently Asked Questions
index() raises ValueError. Test value in my_tuple before calling it, or catch the error with try/except ValueError and handle the missing case yourself.
Search again, starting just after the first match: my_tuple.index(value, my_tuple.index(value) + 1). It raises ValueError if there is no second one.
Always from the beginning. In ("a", "b", "a").index("a", 1) the search starts at 1, but the answer is 2, the real position of that item in the tuple.
Strings have find(), which returns -1 for a missing value, but a tuple only has count() and index(). Write a small helper with try/except ValueError if you want a -1 result.
They search the same way and take the same value, start, and stop arguments. Because a tuple can never change, a position you found stays correct for as long as the tuple exists.