Table Of Contents


Enter search terms or a module, class or function name.


Series.str.replace(pat, repl, n=-1, case=None, flags=0)[source]

Replace occurrences of pattern/regex in the Series/Index with some other string. Equivalent to str.replace() or re.sub().


pat : string or compiled regex

String can be a character sequence or regular expression.

New in version 0.20.0: pat also accepts a compiled regex.

repl : string or callable

Replacement string or a callable. The callable is passed the regex match object and must return a replacement string to be used. See re.sub().

New in version 0.20.0: repl also accepts a callable.

n : int, default -1 (all)

Number of replacements to make from start

case : boolean, default None

  • If True, case sensitive (the default if pat is a string)
  • Set to False for case insensitive
  • Cannot be set if pat is a compiled regex

flags : int, default 0 (no flags)

  • re module flags, e.g. re.IGNORECASE
  • Cannot be set if pat is a compiled regex

replaced : Series/Index of objects


When pat is a compiled regex, all flags should be included in the compiled regex. Use of case or flags with a compiled regex will raise an error.


When repl is a string, every pat is replaced as with str.replace(). NaN value(s) in the Series are left as is.

>>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f', 'b')
0    boo
1    buz
2    NaN
dtype: object

When repl is a callable, it is called on every pat using re.sub(). The callable should expect one positional argument (a regex object) and return a string.

To get the idea:

>>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f', repr)
0    <_sre.SRE_Match object; span=(0, 1), match='f'>oo
1    <_sre.SRE_Match object; span=(0, 1), match='f'>uz
2                                                  NaN
dtype: object

Reverse every lowercase alphabetic word:

>>> repl = lambda m:[::-1]
>>> pd.Series(['foo 123', 'bar baz', np.nan]).str.replace(r'[a-z]+', repl)
0    oof 123
1    rab zab
2        NaN
dtype: object

Using regex groups (extract second group and swap case):

>>> pat = r"(?P<one>\w+) (?P<two>\w+) (?P<three>\w+)"
>>> repl = lambda m:'two').swapcase()
>>> pd.Series(['One Two Three', 'Foo Bar Baz']).str.replace(pat, repl)
0    tWO
1    bAR
dtype: object

Using a compiled regex with flags

>>> regex_pat = re.compile(r'FUZ', flags=re.IGNORECASE)
>>> pd.Series(['foo', 'fuz', np.nan]).str.replace(regex_pat, 'bar')
0    foo
1    bar
2    NaN
dtype: object
Scroll To Top