To replace several substrings in one pandas column, call .str.replace() on that column and assign the returned Series back to it. In pandas 3.0.6, you can pass a dictionary of pattern-to-replacement pairs: df["col"] = df["col"].str.replace({"old1": "new1", "old2": "new2"}). Use regex=False for literal text or regex=True for regular expressions.
Replace multiple substrings with different text
A DataFrame column is a Series, so select the column before using its .str accessor. The pandas 3.0.6 API accepts a dictionary as pat; each key is a pattern and its value is the replacement. When pat is a dictionary, leave repl as None—the dictionary supplies the replacements.
df["col"] = df["col"].str.replace({"foo": "bar", "baz": "qux"})This applies the corresponding substitutions to string values in the selected column. The method returns a transformed Series or Index; assigning it to df["col"] makes the result the DataFrame’s column value. See the pandas Series.str.replace API reference.
Choose literal matching or regular expressions
Match text literally
In the current Series API, regex=False is the default, so string patterns are treated as literal text. To make that intent explicit, write:
#1 Best Overall
df["col"] = df["col"].str.replace("foo", "bar", regex=False)Match several alternatives with one replacement
If all alternatives should be replaced by the same text, combine them in one regular expression and set regex=True:
df["col"] = df["col"].str.replace(r"foo|baz", "replacement", regex=True)Here, either foo or baz is replaced with replacement. Use a dictionary instead when each pattern needs its own replacement. The pandas text-data guide notes that, from pandas 2.0, a single-character pattern with regex=True is treated as a regular expression too.
Use DataFrame.replace for whole-cell values
DataFrame.replace() is the better fit when you want to remap cell values rather than edit matching text within strings. For example, this maps a whole cell value:
df = df.replace({"old": "new"})The DataFrame method has its own argument forms for scalar, list, dictionary, nested-dictionary, and regex replacement. It can target column-specific values with nested mappings; consult the DataFrame.replace API reference for the appropriate mapping shape. Its argument behavior and defaults are separate from those of Series.str.replace().
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteQuick Recap
| Method | Best for | Scope | Pattern behavior |
|---|---|---|---|
df["col"].str.replace(...) |
Changing substrings inside text | A selected Series (column) | regex=False by default; set regex=True for regex matching. A dictionary pattern maps patterns to separate replacement strings. |
df.replace(...) |
Remapping whole cell values or applying DataFrame replacement rules | DataFrame cells, with column-specific forms available | Uses its own to_replace, value, and regex argument forms; see the DataFrame API reference. |
Common mistakes to avoid
- Calling
.str.replace()on the DataFrame. Select a Series first, such asdf["col"]; the usual string-accessor call operates on a Series or Index. - Passing a separate replacement with a dictionary pattern. The dictionary already contains the replacement for each key, so
replmust remainNone. - Forgetting to keep the returned result. Assign the transformed Series back to the column when you want the DataFrame to retain the edits.
- Assuming missing values become strings. The official Series examples show missing values unchanged.
- Applying Series defaults to DataFrame.replace. The two methods have different argument forms and defaults; choose based on whether the target is text inside a cell or the cell value itself.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
