Python Reference
str.replace()
Replace all occurrences of a substring with another string.
Last updated: October 2026
Definition: str.replace(old, new, count=-1) returns a copy of the string with all occurrences of the substring old replaced by new. It does not modify the original string.
🎬 Live Example
Five common replace patterns. Click any button to see the output.
💡 replace returns a new string — strings are immutable.
Basic Syntax
str.replace(old, new, count=-1)
# old — substring to find
# new — replacement string
# count — max replacements (default -1 = all)
# Returns: new str🎯 Parameters
| Parameter | Type | Description |
|---|---|---|
old | str | Substring to replace. |
new | str | Replacement string. |
count | int | Max replacements. -1 = all (default). |
Basic Replacement
"hello world".replace("world", "Python")
# 'hello Python'
"aaa".replace("a", "b")
# 'bbb'
"cat".replace("c", "b")
# 'bat'Limit Replacements with count
"aaa".replace("a", "b", 1)
# 'baa'
"aaa".replace("a", "b", 2)
# 'bba'
"hello hello".replace("hello", "hi", 1)
# 'hi hello'Use case: Replace only the first occurrence of a delimiter when parsing.
Remove Substrings
"hello world".replace(" ", "")
# 'helloworld'
"a-b-c".replace("-", "")
# 'abc'
# Strip specific characters anywhere
"phone: 123-456".replace("-", "")
# 'phone: 123456'Case Sensitivity
"Hello".replace("hello", "Hi")
# 'Hello' (no match — case matters)
"Hello".lower().replace("hello", "hi")
# 'hi'
# Or use regex for case-insensitive
import re
re.sub("hello", "hi", "Hello", flags=re.IGNORECASE)
# 'hi'Real-World: Clean User Input
raw = " Hello, World! "
cleaned = raw.strip().replace(" ", " ")
# 'Hello, World!'
# Remove multiple spaces
import re
re.sub(r"\\s+", " ", raw.strip())
# 'Hello, World!'🎯 replace vs translate vs re.sub
| Method | Use when | Notes |
|---|---|---|
replace | Simple literal replacement | Case-sensitive, no regex |
translate | Character-by-character mapping | Fast, single chars |
re.sub | Pattern matching | Requires regex |
⚠️ Common Mistakes
- Expecting case-insensitive replacement. Lower/upper first or use regex.
- Forgetting to assign.
s.replace(...)alone does nothing. - Using replace for regex. Use
re.subfor patterns. - Assuming replace modifies the string. Strings are immutable.
- Passing count as a string. Must be an integer.
❓ Frequently Asked Questions
What does replace() do in Python?
str.replace(old, new) returns a copy of the string with all occurrences of the substring old replaced by new. It does not modify the original string.
How do I limit the number of replacements?
Pass count as the third argument: 'aaa'.replace('a', 'b', 2) returns 'bba'. Only the first 2 occurrences are replaced.
Is replace case-sensitive?
Yes. replace is case-sensitive. 'Hello'.replace('hello', 'Hi') returns 'Hello' unchanged. Use lower() or regex for case-insensitive replacement.
Does replace work with regex?
No. str.replace does literal substring replacement. For regex, use the re module: re.sub(pattern, replacement, string).
Does replace modify the original string?
No. Strings are immutable in Python. replace returns a new string; the original is unchanged.