Examples
Scalar 'to_replace' and 'value'

In [1]:
import numpy as np
import pandas as pd
In [2]:
s = pd.Series([0, 2, 3, 4, 5])
s.replace(0, 6)
Out[2]:
0    6
1    2
2    3
3    4
4    5
dtype: int64

In [3]:
df = pd.DataFrame({'X': [0, 2, 3, 4, 5],
                   'Y': [6, 7, 8, 9, 1],
                   'Z': ['p', 'q', 'r', 's', 't']})
In [4]:
df.replace(0, 5)
Out[4]:
X Y Z
0 5 6 p
1 2 7 q
2 3 8 r
3 4 9 s
4 5 1 t

List-like 'to_replace'

In [5]:
df.replace([0, 2, 3, 4], 5)
Out[5]:
X Y Z
0 5 6 p
1 5 7 q
2 5 8 r
3 5 9 s
4 5 1 t
In [6]:
df.replace([0, 2, 3, 4], [4, 3, 2, 1])
Out[6]:
X Y Z
0 4 6 p
1 3 7 q
2 2 8 r
3 1 9 s
4 5 1 t
In [7]:
s.replace([2, 3], method='bfill')
Out[7]:
0    0
1    4
2    4
3    4
4    5
dtype: int64

dict-like 'to_replace'

In [8]:
df.replace({0: 20, 1: 80})
Out[8]:
X Y Z
0 20 6 p
1 2 7 q
2 3 8 r
3 4 9 s
4 5 80 t
In [9]:
df.replace({'X': 0, 'Y': 6}, 80)
Out[9]:
X Y Z
0 80 80 p
1 2 7 q
2 3 8 r
3 4 9 s
4 5 1 t
In [10]:
df.replace({'X': {0: 100, 3: 200}})
Out[10]:
X Y Z
0 100 6 p
1 2 7 q
2 200 8 r
3 4 9 s
4 5 1 t

Regular expression 'to_replace'

In [11]:
df = pd.DataFrame({'X': ['bbb', 'fff', 'bii'],
                   'Y': ['abc', 'brr', 'pqr']})
In [12]:
df.replace(to_replace=r'^ba.$', value='new', regex=True)
Out[12]:
X Y
0 bbb abc
1 fff brr
2 bii pqr
In [13]:
df.replace({'X': r'^ba.$'}, {'X': 'new'}, regex=True)
Out[13]:
X Y
0 bbb abc
1 fff brr
2 bii pqr
In [14]:
df.replace(regex=r'^ba.$', value='new')
Out[14]:
X Y
0 bbb abc
1 fff brr
2 bii pqr
In [15]:
df.replace(regex={r'^ba.$': 'new', 'fff': 'pqr'})
Out[15]:
X Y
0 bbb abc
1 pqr brr
2 bii pqr
In [16]:
df.replace(regex=[r'^ba.$', 'fff'], value='new')
Out[16]:
X Y
0 bbb abc
1 new brr
2 bii pqr

Note that when replacing multiple bool or datetime64 objects, the data types in the to_replace parameter
must match the data type of the value being replaced:

In [17]:
df = pd.DataFrame({'X': [True, False, True],
                   'Y': [False, True, False]})
df.replace({'a string': 'new value', True: False}) # raises Traceback (most recent call last): ... TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str'

This raises a TypeError because one of the dict keys is not of the correct type for replacement.

Compare the behavior of s.replace({'p': None}) and s.replace('p', None) to understand the peculiarities
of the to_replace parameter:

In [18]:
s = pd.Series([10, 'p', 'p', 'q', 'p'])

When one uses a dict as the to_replace value, it is like the value(s) in the dict are equalto the value parameter.
s.replace({'p': None}) is equivalent to s.replace(to_replace={'p': None}, value=None, method=None):

In [19]:
s.replace({'p': None})
Out[19]:
0      10
1    None
2    None
3       q
4    None
dtype: object

When value=None and to_replace is a scalar, list or tuple, replace uses the method parameter (default ‘pad’)
to do the replacement. So this is why the ‘p’ values are being replaced by 10 in rows 1 and 2 and ‘q’ in row 4 in this case.
The command s.replace('p', None) is actually equivalent to s.replace(to_replace='p', value=None, method='pad'):

In [20]:
s.replace('p', None)
Out[20]:
0    10
1    10
2    10
3     q
4     q
dtype: object