Python String replace() Method

The Python string replace() method lets you change text inside a string.

This is a beginner-friendly reference page for replace(). You will learn:

  • what replace() does
  • how its syntax works
  • how to replace all matches or only some matches
  • common mistakes to avoid

Quick example

text = "I like cats"
new_text = text.replace("cats", "dogs")
print(new_text)

Output:

I like dogs

Use replace(old, new) to return a new string with matching text changed. The original string is not modified.

What replace() does

replace() changes matching text inside a string.

Key points:

  • It returns a new string
  • The original string stays unchanged
  • It works on exact matches
  • It replaces all matches unless you limit it with count

If you are new to strings, see Python strings explained: basics and examples.

Syntax

string.replace(old, new)
string.replace(old, new, count)

Parameters

  • old = the text to find
  • new = the replacement text
  • count = optional number that limits how many matches are replaced

Basic example

Here is a simple example that replaces one word with another:

text = "I like cats"
new_text = text.replace("cats", "dogs")

print(text)
print(new_text)

Output:

I like cats
I like dogs

Notice what happened:

  • text did not change
  • new_text contains the updated value

This happens because strings are immutable in Python. That means you cannot change a string in place. Methods like replace() return a new string instead.

Replace only the first matches

By default, replace() changes every matching part of the string.

If you only want to replace the first 1 or 2 matches, use the optional count argument.

Replace only the first match

text = "cat cat cat"
result = text.replace("cat", "dog", 1)

print(result)

Output:

dog cat cat

Replace only the first 2 matches

text = "cat cat cat"
result = text.replace("cat", "dog", 2)

print(result)

Output:

dog dog cat

This is useful when you do not want to replace every match in the string.

For more practical examples, see how to replace text in a string in Python.

Replacing characters and spaces

replace() can also change single characters.

Replace one character

text = "banana"
result = text.replace("a", "o")

print(result)

Output:

bonono

Remove spaces

You can remove text by replacing it with an empty string:

text = "a b c"
result = text.replace(" ", "")

print(result)

Output:

abc

This is useful for simple cleanup tasks.

If you need to split text into parts instead of replacing it, see the Python string split() method. If you only want to remove spaces at the beginning or end, the Python string strip() method is often a better choice.

Case sensitivity

replace() is case-sensitive.

That means "cat" and "Cat" are different.

text = "Cat cat CAT"
result = text.replace("cat", "dog")

print(result)

Output:

Cat dog CAT

Only the lowercase "cat" was replaced.

This is a common beginner problem. If your replacement is not happening, check the letter case carefully.

In some cases, converting text first can help. For example, see the Python string lower() method.

What replace() returns

replace() returns a new string.

If no match is found:

  • no error happens
  • the returned string has the same content as the original

Example:

text = "hello"
result = text.replace("x", "y")

print(result)

Output:

hello

Usually, you either store the result in a new variable:

text = "hello world"
new_text = text.replace("world", "Python")

Or reassign it to the same variable:

text = "hello world"
text = text.replace("world", "Python")

Common beginner mistakes

Here are some common mistakes when using replace():

  • Forgetting to save the returned string
  • Expecting replace() to change the original string
  • Using the wrong letter case
  • Confusing replace() with regex-based replacements

Mistake: calling replace() without assigning the result

This does not update text:

text = "I like cats"
text.replace("cats", "dogs")
print(text)

Output:

I like cats

Correct version:

text = "I like cats"
text = text.replace("cats", "dogs")
print(text)

Output:

I like dogs

Mistake: different capitalization

text = "Hello"
print(text.replace("hello", "Hi"))

Output:

Hello

Nothing changed because "hello" and "Hello" are not the same.

Mistake: expecting only one match to change

text = "red red red"
print(text.replace("red", "blue"))

Output:

blue blue blue

If you want only one replacement, use count:

text = "red red red"
print(text.replace("red", "blue", 1))

Output:

blue red red

Mistake: using replace() for the wrong task

Sometimes another method is a better fit:

  • Use split() to break a string into a list
  • Use strip() to remove whitespace from the start or end
  • Use replace() for direct text replacement, not pattern matching

FAQ

Does replace() change the original string?

No. It returns a new string. Strings in Python cannot be changed in place.

What happens if the text is not found?

No error is raised. The returned string will have the same content as the original.

How do I replace only the first match?

Use the third argument:

text.replace(old, new, 1)

Can replace() remove text?

Yes. Replace the target text with an empty string:

text.replace("x", "")

Is replace() case-sensitive?

Yes. Uppercase and lowercase letters are treated as different.

See also