How to Use str.replace in pandas for String Replacement

Use str.replace() in pandas to replace parts of strings in a Series or DataFrame column. It takes the substring or regex pattern to find and the replacement string, returning a new Series with replaced values.

Syntax

The basic syntax of str.replace() in pandas is:

• Series.str.replace(pat, repl, n=-1, case=None, regex=True)

Where:

• pat: The string or regex pattern to find.
• repl: The string to replace the matched pattern.
• n: Number of replacements per string, default is all (-1).
• case: If True, case-sensitive; if False, case-insensitive.
• regex: If True, treat pat as regex; if False, treat as literal string.

python

Series.str.replace(pat, repl, n=-1, case=None, regex=True)

Example

This example shows how to replace all occurrences of 'cat' with 'dog' in a pandas Series.

python

import pandas as pd

# Create a Series with strings
s = pd.Series(['cat and dog', 'dog and cat', 'catcat', 'dog'])

# Replace 'cat' with 'dog'
s_replaced = s.str.replace('cat', 'dog')

print(s_replaced)

Output

0    dog and dog
1    dog and dog
2        dogdog
3           dog
dtype: object

Common Pitfalls

Common mistakes when using str.replace() include:

• Not setting regex=False when replacing literal strings that contain regex special characters, causing unexpected replacements.
• Assuming replacement happens in-place; str.replace() returns a new Series and does not modify the original.
• Using case=False without regex=True can cause errors in older pandas versions.

python

import pandas as pd

s = pd.Series(['price is $5', 'cost is $10'])

# Wrong: special character $ treated as regex
wrong_replace = s.str.replace('$', 'USD')

# Right: treat $ as literal by setting regex=False
right_replace = s.str.replace('$', 'USD', regex=False)

print('Wrong replacement:')
print(wrong_replace)
print('\nRight replacement:')
print(right_replace)

Output

Wrong replacement:
0    price is USD5
1    cost is USD10
Right replacement:
0    price is USD5
1    cost is USD10

Quick Reference

Remember these tips when using str.replace():

• Use regex=False for literal string replacement.
• Use n to limit number of replacements per string.
• Returns a new Series; assign it to a variable or column.
• Supports regex patterns for flexible matching.

Key Takeaways

Use pandas str.replace() to replace substrings in Series or DataFrame string columns.

Set regex=False to replace literal strings safely without regex interpretation.

The method returns a new Series; original data is not changed unless reassigned.

You can limit replacements per string with the n parameter.

Supports case-sensitive or insensitive replacements with the case parameter.