Pandas Series: replace() function

Replace Pandas series values given in to_replace with value

The replace() function is used to replace values given in to_replace with value.

Values of the Series are replaced with other values dynamically. This differs from updating with .loc or .iloc, which require you to specify a location to update with some value.


Series.replace(self, to_replace=None, value=None, inplace=False, limit=None, regex=False, method='pad')
Pandas Series replace image
Name Description Type/Default Value Required / Optional
to_replace   Values that will be replaced.
  • numeric, str or regex:
  • list of str, regex, or numeric:
  • dict:
  • None:
str, regex, list, dict, Series, int, float, or None Required
value Value to replace any values matching to_replace with. For a DataFrame a dict of values can be used to specify which value to use for each column (columns not in the dict will not be filled). Regular expressions, strings and lists or dicts of such objects are also allowed. scalar, dict, list, str, regex
Default Value: None
inplace If True, in place. Note: this will modify any other views on this object (e.g. a column from a DataFrame). Returns the caller if this is True. bool
Default Value: False
limit Maximum size gap to forward or backward fill. int
Default Value: None
regex Whether to interpret to_replace and/or value as regular expressions. If this is True then to_replace must be a string. Alternatively, this could be a regular expression or a list, dict, or array of regular expressions in which case to_replace must be None. bool or same types as to_replace
Default Value: False
method The method to use when for replacement, when to_replace is a scalar, list or tuple and value is None. {‘pad’, ‘ffill’, ‘bfill’, None} Required

Returns: Series - Object after replacement.


  • If regex is not a bool and to_replace is not None.


  • If to_replace is a dict and value is not a list, dict, ndarray, or Series
  • If to_replace is None and regex is not compilable into a regular expression or is a list, dict, ndarray, or Series.
  • When replacing multiple bool or datetime64 objects and the arguments to to_replace does not match the type of the value being replaced


  • If a list or an ndarray is passed to to_replace and value but they are not the same length.



Download the above Notebook from here.

Previous: Concatenate two or more Pandas series
Next: Modify Pandas series in place using non-NA values