Python String `index()` Method

The Python string index() method returns the position of the first match inside a string.

Use it when you want to find where a character or substring appears, and you expect that value to be present. If Python cannot find the value, it raises a ValueError.

Quick example

text = "hello world"
position = text.index("world")
print(position)

# Output:
# 6

Use index() when you want the position of a substring and expect it to exist. If the value is missing, Python raises a ValueError.

What `str.index()` does

str.index() searches a string and gives back the position of the first match.

Key points:

It returns the position of the first match in a string
It works with a single character or a longer substring
The search is case-sensitive
It raises ValueError if the substring is not found

Example:

text = "banana"

print(text.index("a"))     # 1
print(text.index("na"))    # 2

Here:

"a" first appears at index 1
"na" first appears at index 2

Case sensitivity matters:

text = "Hello"

print(text.index("H"))   # 0
# print(text.index("h")) # ValueError

Basic syntax

The syntax is:

string.index(value, start, end)

Parameters:

value: the text to search for
start: optional starting position
end: optional stopping position

You can use just the value:

text = "python"
print(text.index("t"))  # 2

Or include a start position:

text = "banana"
print(text.index("a", 2))  # 3

Or include both start and end:

text = "banana"
print(text.index("a", 2, 5))  # 3

What the return value means

The value returned by index() is a zero-based index.

That means:

Index 0 is the first character
Index 1 is the second character
Index 2 is the third character

Example:

text = "cat"

print(text.index("c"))  # 0
print(text.index("a"))  # 1
print(text.index("t"))  # 2

index() returns only the first matching position.

text = "banana"
print(text.index("a"))  # 1

Even though "a" appears more than once, the method returns only the first match.

If you need to count matches instead, see the str.count() method.

Using `start` and `end`

The start and end arguments let you search only part of the string.

This is useful when the same text appears more than once.

Example with start:

text = "banana"

print(text.index("a"))      # 1
print(text.index("a", 2))   # 3
print(text.index("a", 4))   # 5

In this example:

The first search finds the first "a" at index 1
Starting at index 2 skips that first match
Starting at index 4 finds the last "a"

Example with end:

text = "banana"

print(text.index("n", 0, 4))  # 2

This searches only within part of the string.

One important detail: the returned index still refers to the original string, not a smaller temporary section.

When `index()` causes an error

If the substring is not found, index() raises a ValueError.

Example:

text = "hello"
print(text.index("z"))

Output:

ValueError: substring not found

This is different from str.find(), which returns -1 instead of raising an error.

If the value may not exist, use try and except:

text = "hello"

try:
    position = text.index("z")
    print(position)
except ValueError:
    print("Substring not found")

This helps your program continue running.

If you are dealing with this exact error, see how to fix ValueError: substring not found.

`index()` vs `find()`

index() and find() are very similar, but they behave differently when no match is found.

`index()`

Returns the first match position
Raises an error if nothing is found

text = "hello"
print(text.index("e"))  # 1
# print(text.index("z"))  # ValueError

`find()`

Returns the first match position
Returns -1 if nothing is found

text = "hello"
print(text.find("e"))  # 1
print(text.find("z"))  # -1

Use index() when missing data should be treated as a problem.

Use find() when you want to check safely without an exception.

For a full comparison, see the str.find() method reference or how to check if a string contains a substring in Python.

Common mistakes

Beginners often run into these problems when using index():

Searching for text with the wrong uppercase or lowercase letters
Expecting index() to return -1 when no match exists
Using index() on a value that may not be present
Confusing character position with human counting starting at 1
Assuming index() returns every match instead of the first one

Useful checks while debugging:

print(text)
print(repr(text))
print(text.index("value"))
print(text.find("value"))
print(text.index("value", start, end))

Tips:

Use print(repr(text)) to spot spaces or hidden characters
Use find() if you want to test first without raising an error
Double-check uppercase and lowercase letters
Remember that Python starts counting at 0

FAQ

What does Python string `index()` return?

It returns the zero-based position of the first match in the string.

What happens if the substring is not found?

Python raises a ValueError.

What is the difference between `index()` and `find()`?

index() raises an error if nothing is found. find() returns -1 instead.

Can `index()` search for more than one character?

Yes. It can search for a substring, not just a single character.

Is string `index()` case-sensitive?

Yes. Uppercase and lowercase letters are treated as different.

Python String index() Method

Python String `index()` Method