df.where(cond) keeps values where cond is True and replaces everything else with NaN (or a specified alternative), preserving the DataFrame's original shape.

Syntax

df.where(cond, other=nan)

Deep Dive Course

Unlike boolean indexing, which returns a smaller DataFrame containing only the matching rows, where() returns a DataFrame of the exact same shape as the original, with values that fail the condition replaced, by default with NaN, rather than dropped entirely — this makes it well suited for masking out invalid values in place while keeping every row and column aligned for further calculations. Passing the other parameter lets you substitute a specific value or another DataFrame's aligned values instead of the default NaN.

1Understanding df.where()

💡

Use where() specifically when you need to keep the DataFrame's original shape and replace non-matching values in place, rather than boolean indexing, which instead drops non-matching rows entirely and returns a smaller result.

editor.html

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60))

localhost:3000

2Practical Example

Here is a real-world application of df.where() showing how it is used in production Pandas code.

editor.html

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60, other=0))

localhost:3000

3Best Practices

Follow these guidelines when working with df.where():

1. Use where() when downstream code needs the DataFrame's shape preserved, like for aligned arithmetic with another DataFrame, instead of boolean indexing which shrinks it

2. Pass an explicit other value when NaN isn't the right substitute for values that fail the condition

3. Use boolean indexing instead of where() when you actually want a smaller, filtered DataFrame rather than a same-shaped one with replaced values

⚠️

Tip: Use where() specifically when you need to keep the DataFrame's original shape and replace non-matching values in place, rather than boolean indexing, which instead drops non-matching rows entirely and returns a smaller result.

editor.html

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60))

localhost:3000

Examples

Example 01Basic Usage

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60))

Example 02Advanced Example

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60, other=0))

Best Practices

Use where() when downstream code needs the DataFrame's shape preserved, like for aligned arithmetic with another DataFrame, instead of boolean indexing which shrinks it
Pass an explicit other value when NaN isn't the right substitute for values that fail the condition
Use boolean indexing instead of where() when you actually want a smaller, filtered DataFrame rather than a same-shaped one with replaced values

Interview Question

What's the key difference between boolean indexing with df[condition] and calling df.where(condition)?▼

Hint: Think about what happens to the rows that don't satisfy the condition, and the shape of the result.

Boolean indexing returns a new DataFrame containing only the rows where the condition is True, entirely dropping the non-matching rows, so the result typically has fewer rows than the original. df.where(condition) instead returns a DataFrame with exactly the same shape and the same number of rows as the original, but replaces the values at positions where the condition is False with NaN, or another specified value, rather than removing those rows — it masks values in place instead of filtering them out.

Exercises

MediumPractice using df.where() in a real scenario.

View Solution

import pandas as pd

df = pd.DataFrame({"score": [55, 90, 45, 80]})
print(df.where(df["score"] >= 60))

Frequently Asked Questions

What's the key difference between boolean indexing with df[condition] and calling df.where(condition)?▼

Related Functions

df-maskboolean-indexingdf-isna