How to Replace Text in a String in Python

If you want to change part of a string in Python, the simplest tool is str.replace().

It works well for common tasks like:

changing one word to another
removing part of a string
replacing all matches
replacing only the first few matches

For most beginner cases, this is the right method to use.

Quick answer

text = "Hello world"
new_text = text.replace("world", "Python")
print(new_text)

Output:

Hello Python

Use str.replace(old, new) to replace text in a string. It returns a new string and does not change the original.

What this page helps you do

This page shows you how to:

Replace one word or phrase inside a string
Replace all matching parts of a string
Replace only the first few matches when needed
Understand that strings are immutable in Python

Use `str.replace()` for most text replacement

The basic syntax is:

text.replace(old, new)

old is the text to find
new is the text to insert instead
the method returns a new string

Here is a simple example:

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

print(new_text)

Output:

I like dogs

In this example:

Python looks for "cats"
it replaces it with "dogs"
it gives back a new string

If you are new to strings, see Python strings explained.

Replace all matches

By default, replace() changes every matching occurrence.

text = "red blue red green red"
new_text = text.replace("red", "yellow")

print(new_text)

Output:

yellow blue yellow green yellow

This is useful for simple cleanup and updates.

You can replace:

words
spaces
symbols
short phrases

Example with spaces:

text = "apple    banana    orange"
new_text = text.replace("    ", " ")

print(new_text)

Output:

apple banana orange

Example with symbols:

text = "2024/01/15"
new_text = text.replace("/", "-")

print(new_text)

Output:

2024-01-15

Replace only a limited number of matches

If you only want to replace some matches, use the third argument:

text.replace(old, new, count)

count tells Python how many matches to replace
replacement happens from left to right

Example:

text = "one two one two one"
new_text = text.replace("one", "ONE", 1)

print(new_text)

Output:

ONE two one two one

Replace the first two matches:

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

print(new_text)

Output:

dog dog cat

This is helpful when you only want to change the first occurrence instead of every match.

Strings do not change in place

Strings are immutable in Python. That means they cannot be edited directly.

So this does not change the original string unless you save the result:

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

print(text)

Output:

Hello world

The result was created, but it was not stored anywhere.

To keep the change, save it to a variable:

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

print(new_text)

Output:

Hello Python

You can also assign it back to the same variable:

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

print(text)

Output:

Hello Python

This idea is important in many string tasks, including splitting a string in Python and joining strings in Python.

Case matters when replacing text

replace() is case-sensitive.

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

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

print(new_text)

Output:

Cat dog CAT

Only the lowercase "cat" was replaced.

If nothing gets replaced, check:

uppercase and lowercase letters
spelling
spaces before or after the text
punctuation

Using repr() can help you see hidden spaces:

text = "hello "
print(repr(text))

Output:

'hello '

That trailing space may stop a match from working.

If your goal is cleanup, you may also want to learn how to remove whitespace from a string in Python.

When `replace()` is enough and when it is not

Use replace() when you want to replace an exact piece of text.

Good examples:

replacing "cat" with "dog"
changing "/" to "-"
removing a known word or symbol
replacing a short fixed phrase

Example:

text = "Price: $10"
new_text = text.replace("$", "")

print(new_text)

Output:

Price: 10

replace() is enough for many everyday string tasks.

But it only matches exact text. If the text is different from what you search for, nothing will change.

For example:

text = "Hello, world!"
new_text = text.replace("world", "Python")

print(new_text)

Output:

Hello, Python!

This works because "world" is an exact match inside the string.

If you want full method details, see the Python string replace() method reference. If you need to check whether text exists before replacing it, see how to check if a string contains a substring in Python.

Common mistakes

Here are the most common reasons replace() does not work as expected.

Forgetting to store the returned string

text = "apple pie"
text.replace("apple", "cherry")

print(text)

Output:

apple pie

Fix it by saving the result:

text = "apple pie"
text = text.replace("apple", "cherry")

print(text)

Expecting `replace()` to change the original string directly

Strings cannot be changed in place.

Always remember:

replace() returns a new string
it does not edit the existing string object

Using the wrong letter case

text = "Python"
print(text.replace("python", "Java"))

Output:

Python

Nothing changed because "python" does not exactly match "Python".

Misspelling the old text

text = "I love programming"
print(text.replace("programing", "Python"))

Output:

I love programming

The old text must match exactly.

Expecting only the first match to change

By default, all matches are replaced:

text = "ha ha ha"
print(text.replace("ha", "ho"))

Output:

ho ho ho

If you only want the first match, use count:

text = "ha ha ha"
print(text.replace("ha", "ho", 1))

Output:

ho ha ha

Helpful debugging checks

If your replacement is not working, these quick checks can help:

print(text)
print(repr(text))
print(text.replace('old', 'new'))
print(text.count('old'))
print(type(text))

What these help you check:

print(text) shows the current value
print(repr(text)) shows hidden spaces or escape characters
print(text.replace('old', 'new')) lets you test the replacement directly
print(text.count('old')) shows how many matches exist
print(type(text)) confirms that text is actually a string

Example:

text = "cat cat dog"

print(text)
print(repr(text))
print(text.replace("cat", "bird"))
print(text.count("cat"))
print(type(text))

Output:

cat cat dog
'cat cat dog'
bird bird dog
2
<class 'str'>

FAQ

Does `replace()` change the original string?

No. It returns a new string. You must save the result.

How do I replace only the first match?

Use the third argument:

text.replace(old, new, 1)

Why did nothing get replaced?

The exact text may not match. Check:

spelling
spaces
punctuation
uppercase and lowercase letters

Can I replace multiple different words at once?

Not in one basic replace() call.

For simple cases, use multiple calls:

text = "red blue green"
text = text.replace("red", "yellow")
text = text.replace("blue", "purple")

print(text)

Output:

yellow purple green