Pandas where and mask
last modified November 17, 2026 Python 3.15
A boolean mask is a set of True and False
values that marks which elements we are interested in. The Pandas methods
where and mask use such a mask to replace values while
keeping the original shape of the data. They are opposites: where
keeps the values where the condition is true and replaces the rest, while
mask replaces the values where the condition is true.
This article works through both methods on Series and DataFrames, shows how to
supply a replacement value with other, how a condition is applied
across a whole table, and how conditions can be chained. All examples were run
with pandas 3.1.1.
where on a Series
Calling where with a condition keeps each value for which the
condition is True and substitutes NaN (the standard
marker for a missing value) everywhere the condition is False.
Because NaN is a floating-point value, the resulting Series has a
float64 dtype even though the input held integers.
import pandas as pd s = pd.Series([1, 2, 3, 4, 5]) print(s.where(s > 2))
The condition s > 2 is true for 3, 4 and 5, so those three
values survive. The values 1 and 2 become NaN, shown at index
positions 0 and 1.
$ python where_series.py 0 NaN 1 NaN 2 3.0 3 4.0 4 5.0 dtype: float64
Providing a replacement with other
The second argument, other, supplies the replacement instead of
NaN. We write s.where(condition, other) to put our own
value wherever the condition is false. Since the replacement here is the
integer 0, the result stays an integer Series.
import pandas as pd s = pd.Series([1, 2, 3, 4, 5]) print(s.where(s > 2, 0))
The first two entries have been replaced by 0, while 3, 4 and 5 are left as
they were. The other argument can also be a Series or a DataFrame
whose labels line up with the data, not just a single number.
$ python where_other.py 0 0 1 0 2 3 3 4 4 5 dtype: int64
mask
mask is the mirror image of where: it replaces the
values where the condition is True and keeps the rest. Like
where it accepts an other argument, so we can choose
the replacement rather than getting NaN. In the example we run it
both ways.
import pandas as pd s = pd.Series([1, 2, 3, 4, 5]) print(s.mask(s > 2)) print() print(s.mask(s > 2, -1))
The first result keeps 1 and 2 and turns 3, 4 and 5 into NaN; the
second keeps 1 and 2 and writes -1 in their place. Compare this with the
where output above: the two methods select opposite halves of the
same Series.
$ python mask_series.py 0 1.0 1 2.0 2 NaN 3 NaN 4 NaN dtype: float64 0 1 1 2 2 -1 3 -1 4 -1 dtype: int64
Boolean masks on a DataFrame
A condition built from a DataFrame produces another DataFrame of booleans with
the same shape. Applying where with that mask carries out the
replacement cell by cell across the whole table. This cell-by-cell application
of one rule to every element is what we mean by broadcasting the mask
over the DataFrame.
import pandas as pd
df = pd.DataFrame({'A': [1, 5, 3], 'B': [4, 2, 6]})
print(df.where(df > 2, 0))
Every value greater than 2 is kept and every other value becomes 0. In column A the leading 1 is replaced; in column B the middle 2 is replaced. The three rows and two columns of the original table are preserved.
$ python where_dataframe.py A B 0 0 4 1 5 0 2 3 6
Chained conditions
Conditions can be joined with the & (and) and
| (or) operators. Each part must be wrapped in parentheses because
these operators bind differently from the comparison operators. The combined
boolean mask is then passed to where in the usual way.
import pandas as pd
df = pd.DataFrame({'A': [1, 5, 3, 7], 'B': [4, 2, 6, 8]})
cond = (df > 2) & (df < 7)
print(df.where(cond, 0))
Here a cell is kept only when it lies strictly between 2 and 7. The value 7 in column A and the value 8 in column B fail the upper bound and are replaced by 0, as are the small values 1 and 2.
$ python where_chained.py A B 0 0 4 1 5 0 2 3 6 3 0 0
How this differs from boolean indexing
Boolean indexing uses a mask to
select rows, so it throws away the rows that fail the test and
changes the number of rows. where and mask never drop
rows: they keep the table the same size and change only the cell values. The
rename and replace methods, covered in the
rename and replace tutorial, work
differently again: they substitute values or labels that match a given name or
mapping, rather than testing a boolean condition. The example contrasts row
filtering with where on the same DataFrame.
import pandas as pd
df = pd.DataFrame({'A': [1, 5, 3], 'B': [4, 2, 6]})
print(df[df['A'] > 2])
print()
print(df.where(df > 2, 0))
The boolean index returns two rows, those with index 1 and 2, and keeps their
values untouched. The where call returns all three rows with the
failing cells set to 0. Choose the first form when you want fewer rows and the
second when you want to clean values in place.
$ python where_vs_boolean.py A B 1 5 2 2 3 6 A B 0 0 4 1 5 0 2 3 6
Source
Pandas DataFrame.where Documentation, Pandas DataFrame.mask Documentation, and Pandas Indexing Documentation
In this article we have kept values with where, replaced values
with mask, supplied custom replacements through
other, broadcast conditions over a DataFrame, chained tests with
&, and seen how these methods differ from row filtering. For
selecting rows see Pandas boolean
indexing, and for name-based substitutions see
Pandas rename and replace.
Author
List all Pandas tutorials.