PythonBeginner.help

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
b0-6a1-5n2-4a3-3n4-2a5-1[2:4]
In "banana", index("na") returns 2 — the start of the first na.

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.

See also #

Press Esc to close