Normalize labels
Standardizing categorical data before analysis.
Pandas · Module
df.replace
Replaces matching values in a DataFrame with specified alternatives. It supports scalar, list, dictionary, and regular-expression-based replacements, and returns a new frame unless inplace=True.
How it works
DataFrame.replace searches the frame for values matching to_replace and substitutes them with value. It returns a changed copy by default, while inplace=True applies the operation to the existing frame; dictionaries can express different mappings or column-specific replacements.
Syntax
DataFrame.replace(*to_replace=None*, *value=<no_default>*, ***, *inplace=False*, *regex=False*)Parameters
| Name | Type | Description |
|---|---|---|
to_replace | str, regex, list, dict, Series, int, float, or None | Values to search for and replace; accepts strings, regular expressions, lists, dictionaries, Series, numbers, or None. |
value | scalar, dict, list, str, regex, default None | Replacement value for matches; it may be a scalar, dictionary, list, string, regular expression, or None. |
inplace | bool, default False | Whether to modify the existing DataFrame instead of returning a new result. |
regex | bool or same types as to_replace, default False | Whether to interpret to_replace and/or value as regular expressions. |
Returns
DataFrame or None if inplace=True
Key points
- Use the method to substitute matching DataFrame values with another value.
- Matching is based on values throughout the object, not on fixed row or column positions.
- A mapping is useful when several source values need distinct replacements.
- Numeric matching uses equality between the cell value and the numeric target.
- Without regex interpretation, a string target must match the cell string exactly.
- Regular-expression matching enables transformations based on text patterns.
Common mistakes
- When paired lists are supplied, their lengths must match.
- If regex patterns are supplied through regex, to_replace must be omitted.
- The method parameter applies only to the specified replacement shapes when value is None.
Example: Replace values in a DataFrame
import pandas as pd
frame = pd.DataFrame({"status": ["new", "pending", "new"], "score": [1, 2, 1]})
cleaned = frame.replace({"new": "open", "pending": "waiting", 1: 10})
print(cleaned)Creates a new DataFrame with selected scalar values replaced across the data.
When to use it
Clean numeric markers
Converting sentinel numeric values into meaningful values.
Regex cleanup
Applying text-pattern transformations across columns.
Interview questions
QHow does DataFrame.replace differ from location-based assignment?
It matches values described by to_replace and substitutes the corresponding value. Unlike .loc or .iloc, it selects values by their contents rather than requiring an explicit location.
Follow-up: How would you perform pattern-based replacement? Set regex=True, or provide regular expressions in the supported regex forms.
QHow can different replacements be specified in one call?
A dictionary can map several existing values to their replacements. For a DataFrame, a dictionary value can also specify replacements by column, leaving columns absent from that mapping unchanged.
Follow-up: What happens when regex=True with two lists? Strings in both lists are interpreted as regular expressions rather than literal matches.
QWhat does inplace control?
The default is inplace=False, so the operation returns a replaced DataFrame and does not modify the original. Setting inplace=True performs the operation on the existing object.
Follow-up: Which option controls pattern interpretation? The regex parameter determines whether to interpret to_replace and/or value as regular expressions.
Related
Series.replaceDataFrame.maskDataFrame.whereDataFrame.fillna