{"id":4941,"date":"2026-09-30T17:05:07","date_gmt":"2026-09-30T17:05:07","guid":{"rendered":"https:\/\/www.askpython.com\/?p=4941"},"modified":"2026-09-30T17:05:07","modified_gmt":"2026-09-30T17:05:07","slug":"python-replace-function","status":"publish","type":"post","link":"https:\/\/www.askpython.com\/python\/string\/python-replace-function","title":{"rendered":"Python replace() function"},"content":{"rendered":"\n\n\n

Calling `”Python python PYTHON”.replace(“python”, “Ruby”)` changes only the lowercase match. I appreciate the `count` argument because it caps how many matches change.<\/p>\n\n\n\n

Pass the old and new text to `str.replace()` and check the returned string. Compare that returned string with the original to see which text changed.<\/p>\n\n\n\n

What str.replace() changes<\/h2>\n\n\n\n

str.replace(old, new, count=-1) searches a string for an exact substring and returns a copy<\/a> with matching occurrences replaced.<\/p>\n\n\n\n

By default, it changes every match. Set count to limit the number of replacements.<\/p>\n\n\n\n

Assign the returned string when later code needs the changed text, because the source string stays unchanged.<\/p>\n\n\n

\npython3 -c 'text = "ref-17, ref-28"; result = text.replace("ref-", "INV-"); print(result); print(text)' \n<\/pre><\/div>\n\n\n
\"Terminal
The replacement result is printed first, followed by the unchanged source string.<\/figcaption><\/figure>\n\n\n\n
Python strings are immutable, so replace() returns a result instead of changing the original string. Assign that result back to the same name if later code should use the changed text.<\/p>\n\n\n\n
What you need before replacing text<\/h2>\n\n\n\n
Call replace() on the string that contains the text you want to change, then pass the exact substring and its replacement.<\/p>\n\n\n\n
Argument<\/th>What it supplies<\/th><\/tr><\/thead>
old<\/td>The literal substring to find<\/td><\/tr>
new<\/td>The text inserted for each match<\/td><\/tr>
count<\/td>An optional limit, defaulting to every match<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Matching is case-sensitive and literal. Python’s re.sub()<\/a> handles regular-expression matching and can ignore case with re.IGNORECASE.<\/p>\n\n\n\n
Use replace() for exact text changes<\/h2>\n\n\n\n
Choose the example by the object you have and how many matches you want to change.<\/p>\n\n\n\n
Replace every exact match<\/h3>\n\n\n\n
The method replaces each non-overlapping match, and the replacement can have a different length from the text it finds.<\/p>\n\n\n
\ntext = "Py and Py"\nprint(text.replace("Py", "Python"))\n<\/pre><\/div>\n\n\n
Both matches become Python, and the replacement’s greater length does not change the method’s search. The original variable still refers to the unchanged string.<\/p>\n\n\n\n
Limit how many matches change<\/h3>\n\n\n\n
Count limits the number of matches, so I saw the final warn stay unchanged after the first two replacements. A zero count changes none, and -1 keeps the all-matches default.<\/p>\n\n\n
\npython3 -c 'print("warn: warn: warn".replace("warn", "hold", 2))'\n<\/pre><\/div>\n\n\n
\"Terminal
count=2 changes the first two matches and leaves the last warn in place.<\/figcaption><\/figure>\n\n\n\n
Match capitalization or a regular expression<\/h3>\n\n\n\n
str.replace() matches exact capitalization, so re.sub() fits when a regular expression must ignore case.<\/p>\n\n\n
\nimport re\n\ntext = "Python python PYTHON"\nprint(text.replace("python", "Ruby"))\nprint(re.sub("python", "Ruby", text, flags=re.IGNORECASE))\n<\/pre><\/div>\n\n\n
The literal call changes lowercase python only, and re.IGNORECASE makes re.sub() match each capitalization.<\/p>\n\n\n\n
Replace text inside a list<\/h3>\n\n\n\n
A list has no string replace() method, so call the method on each string element and collect the results. A list comprehension creates a new list while leaving the input list intact.<\/p>\n\n\n
\nwords = ["red cat", "blue cat"]\nupdated = [word.replace("cat", "dog") for word in words]\nprint(words)\nprint(updated)\n<\/pre><\/div>\n\n\n
For a list of numbers, use a list comprehension that compares each value with the target number.<\/p>\n\n\n\n
Chain replacements in order<\/h3>\n\n\n\n
Each call receives the previous result, so a later replacement can change text inserted by an earlier call.<\/p>\n\n\n
\npython3 -c 'print("cat".replace("cat", "dog").replace("dog", "fox"))'\n<\/pre><\/div>\n\n\n
\"Terminal
The second replace call receives the first call\u2019s result and changes dog to fox.<\/figcaption><\/figure>\n\n\n\n
Use replace() on a pandas column<\/h2>\n\n\n\n
A pandas Series is a one-dimensional labeled sequence, often a DataFrame column. Its str accessor applies a string operation to each value that supports it, and leaves missing values unchanged.<\/p>\n\n\n\n
The pandas accessor accepts case and regex controls. str.replace() takes an optional count argument.<\/p>\n\n\n\n
If uv is installed, this command supplies pandas for one run and performs a case-insensitive literal replacement.<\/p>\n\n\n
\nuv run --with pandas python -c 'import pandas as pd; s = pd.Series(["Python", "python", "PYTHON", "JavaScript"]); print(s.str.replace("python", "Ruby", case=False, regex=False).to_list())'\n<\/pre><\/div>\n\n\n
\"Pandas
Series.str.replace with case=False and regex=False replaces the Python variants but leaves JavaScript unchanged.<\/figcaption><\/figure>\n\n\n\n
Call<\/th>What it changes<\/th>Useful option<\/th><\/tr><\/thead>
str.replace()<\/td>Substrings in one Python string<\/td>count limits matches<\/td><\/tr>
Series.str.replace()<\/td>Matching text in each Series value<\/td>case and regex control matching<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
case=False matches each capitalization of Python. regex=False keeps the search literal, so JavaScript stays unchanged.<\/p>\n\n\n\n
Where str.replace() stops<\/h2>\n\n\n\n
The edge cases come from what counts as a match and which object owns the method. An empty old value behaves differently from an empty replacement.<\/p>\n\n\n\n