How to replace all occurrences of a string in Python

String manipulation is a daily task for Python developers, and replacing specific substrings is one of the most common operations. Whether you are sanitizing user input, refactoring legacy code, or formatting template strings, knowing how to efficiently replace text is essential.

Since Python strings are immutable (meaning they cannot be changed after they are created), "replacing" a string actually involves creating a brand new string with the desired modifications. In this guide, we will explore the standard methods to replace all occurrences of a string, along with advanced techniques for pattern matching.

The Standard Approach: Using str.replace()

The most direct and Pythonic way to replace substrings is using the built-in string method replace(). By default, this method replaces every instance of the target substring with a new value.

text = "I like Java. Java is good."
new_text = text.replace("Java", "Python")

print(new_text)
# Output: I like Python. Python is good.

This method is highly optimized in C and is the fastest option for simple, literal string replacements. It does not require importing any external modules.

Controlling the Number of Replacements

Sometimes, you might not want to replace every occurrence. For example, you might only want to correct the first error in a log file or change the first delimiter. The replace() method accepts an optional third argument: count.

sentence = "apple apple apple"
# Replace only the first 2 occurrences
result = sentence.replace("apple", "orange", 2)

print(result)
# Output: orange orange apple

In this example, the third "apple" remains untouched because we limited the operation to the first two matches.

Advanced Replacements with re.sub()

The standard replace() method is perfect for exact matches, but it falls short when you need to match patterns. For instance, what if you want to replace multiple spaces with a single space, or remove all digits? For these scenarios, Python's re (regular expression) module provides the sub() function.

import re

text = "User    Input   With   Spaces"
# Replace 1 or more whitespace characters with a single comma
clean_text = re.sub(r'\s+', ',', text)

print(clean_text)
# Output: User,Input,With,Spaces

The re.sub() function is incredibly powerful. It takes a regex pattern, a replacement string, and the original text. It is the industry standard for cleaning messy data.

Case-Insensitive Replacement

A common limitation of the standard replace() method is that it is case-sensitive. If you try to replace "bad" with "good", it won't catch "Bad" or "BAD". To handle this, we can use re.sub() with the re.IGNORECASE flag.

import re

text = "Bad habits lead to bad results."
# Compile a pattern with the Ignore Case flag
pattern = re.compile("bad", re.IGNORECASE)
result = pattern.sub("good", text)

print(result)
# Output: good habits lead to good results.

Chaining Replacements

If you need to perform multiple different replacements on the same string (e.g., replacing "a" with "1" and "b" with "2"), you can chain the replace() calls. However, be readable with your code.

text = "abc"
result = text.replace("a", "1").replace("b", "2").replace("c", "3")
print(result)
# Output: 123

Conclusion

For 90% of use cases, Python's built-in replace() method is sufficient, readable, and fast. It handles replacing all occurrences by default. However, when your requirements grow to include pattern matching or case insensitivity, stepping up to the re module allows for robust text processing. Understanding the difference ensures you write code that is not only functional but also performant.