df.mask(cond) is the logical inverse of where() — it replaces values where cond is True (rather than keeping them), leaving values where cond is False untouched.

Syntax

df.mask(cond, other=nan)

Deep Dive Course

mask() and where() are complementary: where(cond) keeps values where cond is True and replaces the rest, while mask(cond) replaces values where cond is True and keeps the rest — calling mask() with a condition produces exactly the same result as calling where() with that same condition negated. It's useful when it's more natural to express the condition for what you want to remove or mask out, rather than what you want to keep.

1Understanding df.mask()

💡

df.mask(cond) is exactly equivalent to df.where(~cond) — pick whichever one lets you express your actual condition more naturally, rather than always writing an awkward double-negative to force one into the other.

editor.html

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100))

localhost:3000

2Practical Example

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

editor.html

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100, other=100))

localhost:3000

3Best Practices

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

1. Use mask() when the condition naturally describes what should be replaced/hidden, and where() when it naturally describes what should be kept, for whichever reads more clearly

2. Pass an explicit other value to mask() when NaN isn't the right substitute for the masked-out positions

3. Remember mask()'s and where()'s condition roles are exact opposites of each other — double check which one matches your actual intent before using either

⚠️

Tip: df.mask(cond) is exactly equivalent to df.where(~cond) — pick whichever one lets you express your actual condition more naturally, rather than always writing an awkward double-negative to force one into the other.

editor.html

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100))

localhost:3000

Examples

Example 01Basic Usage

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100))

Example 02Advanced Example

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100, other=100))

Best Practices

Use mask() when the condition naturally describes what should be replaced/hidden, and where() when it naturally describes what should be kept, for whichever reads more clearly
Pass an explicit other value to mask() when NaN isn't the right substitute for the masked-out positions
Remember mask()'s and where()'s condition roles are exact opposites of each other — double check which one matches your actual intent before using either

Interview Question

Why is df.mask(cond) considered the exact inverse of df.where(cond)?▼

Hint: Think about what each function keeps versus replaces, for the same condition.

where(cond) keeps the original value wherever cond evaluates to True and replaces it wherever cond is False. mask(cond) does exactly the opposite: it replaces the original value wherever cond is True and keeps it wherever cond is False. Since these two behaviors are precise opposites of each other for the exact same condition, calling mask(cond) always produces an identical result to calling where() with that same condition negated, which is why they're described as inverse operations of one another.

Exercises

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

View Solution

import pandas as pd

df = pd.DataFrame({"temperature": [72, 105, 68, 98]})
print(df.mask(df["temperature"] > 100))

Frequently Asked Questions

Why is df.mask(cond) considered the exact inverse of df.where(cond)?▼

Related Functions

df-whereboolean-indexingdf-isna