Python .replace(): Simple Method, Three Things Worth Knowing

Q: Why does Python replace not change my string?

Because strings are immutable and .replace() returns a new string rather than modifying the original. You have to assign the result: text = text.replace(old, new). Calling text.replace(old, new) on its own computes the new string and discards it, silently and without any error - which is why this is the single most common mistake with the method. Every string method works this way.

Q: What is the difference between replace and re.sub in Python?

.replace() matches an exact literal substring and never interprets special characters. re.sub() matches a regular expression pattern. Use .replace() when you know the exact text - it is faster and cannot surprise you with escaping. Use re.sub() when you need a pattern, such as collapsing runs of whitespace or matching case-insensitively, which .replace() cannot express.

Q: How do I replace only the first occurrence in Python?

Pass the count argument: text.replace(old, new, 1) replaces only the first match from the left. This is genuinely useful for parsing lines where the first delimiter is structural and later ones are part of the data. There is no built-in for replacing only the last occurrence - use str.rpartition() for that.

Q: How do I replace multiple different substrings at once?

For single characters, use str.translate() with a table from str.maketrans() - it does one pass and avoids cascading. For multi-character mappings, a single re.sub() with an alternation and a replacement function works. Avoid chaining .replace() calls for a mapping: each one runs over the previous result, so an earlier replacement's output can be matched by a later rule.

Q: Is .replace() case sensitive in Python?

Yes. .replace() matches exactly, so "Cat".replace("cat", "dog") returns "Cat" unchanged. For case-insensitive replacement use re.sub(pattern, replacement, text, flags=re.IGNORECASE). Lowercasing the whole string first works only if you do not need the original casing preserved, which usually you do.

"hello".replace("l", "L") returns "heLLo" - the method takes the substring to find, the substring to put in its place, and an optional count limiting how many replacements it makes. It returns a new string and never modifies the original, because Python strings are immutable. That immutability is the source of the one bug everyone writes once: calling .replace() and then wondering why nothing changed. Three things separate people who use this method well from people who fight it - immutability, the fact that it is literal rather than regex, and the count argument nobody remembers exists.

This is a method you learn in a minute and then misuse for months. Not because it is subtle, but because two of its three interesting properties are invisible until they bite.

The signature
It returns a new string. It does not modify anything.
It is literal, not a regex
The count argument is more useful than it looks
Replacing many things at once
How this fits the rest of the stack
FAQ

The signature

text = "the cat sat on the mat"

text.replace("cat", "dog")
# 'the dog sat on the mat'

# Optional third argument: how many to replace.
text.replace("the", "a", 1)
# 'a cat sat on the mat'

# Removing is replacing with nothing.
text.replace(" ", "")
# 'thecatsatonthemat'

That is the entire API: str.replace(old, new, count=-1). Default count is every occurrence. No matches is not an error - you get the original string back, unchanged and uncomplaining.

It returns a new string. It does not modify anything.

The bug, in its natural habitat:

name = "  alice  "
name.replace(" ", "")
print(name)
# '  alice  '   <- unchanged, and no error told you

The method did exactly what it promised - it built a new string and returned it. You threw the return value away. Python strings are immutable, so nothing can modify a string in place, ever.

name = name.replace(" ", "")   # assign the result
print(name)
# 'alice'

This is silent, which is what makes it worth naming. There is no error and no warning. The code runs, does nothing, and the wrong value flows onward. Every string method behaves this way - .strip(), .upper(), .lower(), all of them return new strings - so learning it once fixes a whole category.

A related consequence: chained replaces each build a new string.

clean = raw.replace("\r", "").replace("\t", " ").replace("  ", " ")

This is fine and readable for a few replacements. In a loop over a large file it allocates a new string per call per line, and at that point re.sub or str.translate is the better tool.

It is literal, not a regex

.replace() matches exact substrings. It does not interpret ., *, [, or anything else.

"a.b.c".replace(".", "-")
# 'a-b-c'   - the dot is a literal dot, not any character

This is a feature. When you want to replace a literal string, .replace() cannot surprise you the way a regex can, and you never escape anything. Reach for re.sub only when you genuinely need pattern matching:

import re

# Collapse any run of whitespace - .replace() cannot express this.
re.sub(r"\s+", " ", text)

# Case-insensitive replacement - also regex territory.
re.sub(r"cat", "dog", text, flags=re.IGNORECASE)

The rule of thumb: if you know the exact string, use .replace(). If you know a shape, use re.sub. Using regex for a literal replacement is slower and gives you an escaping problem you did not need to have.

The count argument is more useful than it looks

The third argument caps the number of replacements from the left, and it solves problems that otherwise turn into slicing.

path = "usr/local/bin/tool"

# Only the first separator.
path.replace("/", " > ", 1)
# 'usr > local/bin/tool'

Where this genuinely helps: parsing lines where the first delimiter is structural and the rest are data. A log line of timestamp level message with: colons splits badly on every colon and cleanly on the first one. count lets you say first only without reaching for a regex or an index dance.

There is no built-in way to replace only the last occurrence. The idiom is rsplit:

def replace_last(s, old, new):
    head, sep, tail = s.rpartition(old)
    return head + new + tail if sep else s

Replacing many things at once

When you have a mapping rather than a single pair, chaining gets ugly and subtly wrong - each replace runs over the output of the last, so an earlier replacement’s output can be matched by a later rule.

# Bug: the first replace produces text the second one matches.
"a".replace("a", "b").replace("b", "c")
# 'c', not 'b'

For single characters, str.translate does it in one pass:

table = str.maketrans({"a": "b", "b": "c"})
"ab".translate(table)
# 'bc'   - one pass, no cascade

For multi-character mappings, a single re.sub with an alternation and a function does the same job in one pass. The general principle is worth holding onto: sequential replaces cascade, single-pass replacements do not, and the cascade is the kind of bug that survives review because each individual line looks correct.

How this fits the rest of the stack

String handling is not usually where your bill comes from - but the code doing it runs somewhere, and text processing that allocates a new string per line over a large file turns into real CPU time and real memory. That is the sort of thing that quietly decides whether a worker fits in the instance you picked. The RunxBuild hosting calculator shows compute, memory, storage, and bandwidth as separate line items so the size of the box is a decision you make with numbers. The RunxBuild dashboard is where the team watches what it actually consumes.

Useful related references:

FAQ

Why does Python replace not change my string?

Because strings are immutable and .replace() returns a new string rather than modifying the original. You have to assign the result: text = text.replace(old, new). Calling text.replace(old, new) on its own computes the new string and discards it, silently and without any error - which is why this is the single most common mistake with the method. Every string method works this way.

What is the difference between replace and re.sub in Python?

.replace() matches an exact literal substring and never interprets special characters. re.sub() matches a regular expression pattern. Use .replace() when you know the exact text - it is faster and cannot surprise you with escaping. Use re.sub() when you need a pattern, such as collapsing runs of whitespace or matching case-insensitively, which .replace() cannot express.

How do I replace only the first occurrence in Python?

Pass the count argument: text.replace(old, new, 1) replaces only the first match from the left. This is genuinely useful for parsing lines where the first delimiter is structural and later ones are part of the data. There is no built-in for replacing only the last occurrence - use str.rpartition() for that.

How do I replace multiple different substrings at once?

For single characters, use str.translate() with a table from str.maketrans() - it does one pass and avoids cascading. For multi-character mappings, a single re.sub() with an alternation and a replacement function works. Avoid chaining .replace() calls for a mapping: each one runs over the previous result, so an earlier replacement’s output can be matched by a later rule.

Is .replace() case sensitive in Python?

Yes. .replace() matches exactly, so "Cat".replace("cat", "dog") returns "Cat" unchanged. For case-insensitive replacement use re.sub(pattern, replacement, text, flags=re.IGNORECASE). Lowercasing the whole string first works only if you do not need the original casing preserved, which usually you do.