pandas where() — keep or replace values by condition

What it does

df.where(cond) returns a frame of the same shape where cells satisfying cond keep their value and everything else becomes NaN. Pass other= and the losing cells get that value instead — a scalar, a Series, a similarly-shaped DataFrame, even a callable. The boolean twin mask() does the exact opposite: df.mask(cond) wipes the cells where cond is True. Together they cover 'blank the bad data' and 'replace the bad data' without touching row count.

Why it matters

Real data arrives dirty: sensor glitches read as -1, capped meters top out, a probe fails and needs a calibration value instead. Boolean indexing and query() answer 'which rows do I keep?' — but fixing values means keeping the row and patching the cell. That is where()'s whole job, and it does it with label alignment: hand it a lookup table keyed by column name and it patches the right cells from the right columns. np.where() cannot do that; it collapses everything to a bare array and forgets the index.

Example

$ df = pd.DataFrame({"city": ["Berlin", "Paris", "Rome", "Oslo"], "pm25": [24, -1, 31, 19]})
df.pm25.where(df.pm25 >= 0)

0    24.0
1     NaN
2    31.0
3    19.0
Name: pm25, dtype: float64

$ sales = pd.Series([120, 87, 300, 95])
sales.where(sales <= 100, 100)

0    100
1     87
2    100
3     95
dtype: int64

$ measured = pd.DataFrame({"sensor_a": [0.98, 0.11], "sensor_b": [0.75, 0.40]})
calibrated = pd.DataFrame({"sensor_a": [1.00, 1.00], "sensor_b": [0.90, 0.90]})
measured.where(measured > 0.5, calibrated)

   sensor_a  sensor_b
0      0.98      0.75
1      1.00      0.90

$ df2 = pd.DataFrame({"city": ["Berlin", "Paris", "Rome"], "pm25": [24, 19, 31], "year": [2024, 2024, 2025]})
df2.where((df2.pm25 < 30) & (df2.year == 2024))

     city  pm25    year
0  Berlin  24.0  2024.0
1   Paris  19.0  2024.0
2     NaN   NaN     NaN

Common flags

df.where(cond)

keep cells where cond is True, everything else becomes NaN

df.where(cond, other)

other: scalar, Series, same-shape DataFrame, or callable — the replacement values

df.mask(cond, other)

the inverted twin: replace where cond is True (mask(c) ≡ where(~c))

cond as callable

df.where(lambda d: d.pm25 > 20) — the condition is computed on the whole frame

axis=0|1

alignment axis when other is a Series — axis=0 aligns per column, axis=1 per row

inplace=True

mutate the frame instead of returning a copy (defaults to False; discouraged)