df.replace() substitutes specified values throughout a DataFrame (or Series) with other values, supporting exact matches, lists, dicts, and regex patterns.

Syntax

df.replace(to_replace, value=None, regex=False)

Deep Dive Course

replace() can substitute a single value everywhere it appears, replace multiple different values with the same new value using a list, or map several distinct old values to different new values at once using a dict. Passing regex=True lets to_replace be a regular expression pattern instead of an exact value, matching and replacing based on a pattern rather than requiring an identical string.

1Understanding df.replace()

💡

Use a dict with replace(), mapping each old value to its corresponding new value, to remap several distinct values to different new values in a single call, rather than chaining multiple separate replace() calls.

editor.html

import pandas as pd

df = pd.DataFrame({"status": ["Y", "N", "Y", "N"]})
print(df.replace({"Y": "Yes", "N": "No"}))

localhost:3000

2Practical Example

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

editor.html

import pandas as pd

df = pd.DataFrame({"phone": ["555-1234", "555-5678"]})
print(df.replace(r"555-", "", regex=True))

localhost:3000

3Best Practices

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

1. Use a dict argument to replace() when different old values need to map to different new values, instead of chaining multiple replace() calls

2. Pass regex=True when the values to replace are better described by a pattern than an exact literal match

3. Prefer replace() over manual boolean-indexing assignment for straightforward value substitution, since it's more concise and handles multiple mappings at once

⚠️

Tip: Use a dict with replace(), mapping each old value to its corresponding new value, to remap several distinct values to different new values in a single call, rather than chaining multiple separate replace() calls.

editor.html

import pandas as pd

df = pd.DataFrame({"status": ["Y", "N", "Y", "N"]})
print(df.replace({"Y": "Yes", "N": "No"}))

localhost:3000

Examples

Example 01Basic Usage

import pandas as pd

df = pd.DataFrame({"status": ["Y", "N", "Y", "N"]})
print(df.replace({"Y": "Yes", "N": "No"}))

Example 02Advanced Example

import pandas as pd

df = pd.DataFrame({"phone": ["555-1234", "555-5678"]})
print(df.replace(r"555-", "", regex=True))

Best Practices

Use a dict argument to replace() when different old values need to map to different new values, instead of chaining multiple replace() calls
Pass regex=True when the values to replace are better described by a pattern than an exact literal match
Prefer replace() over manual boolean-indexing assignment for straightforward value substitution, since it's more concise and handles multiple mappings at once

Interview Question

How would you replace several different values with different corresponding new values in a single call to replace()?▼

Hint: Think about which argument type lets you express a full old-value-to-new-value mapping.

Pass a dict as the to_replace argument, where each key is an old value and its corresponding value is the new replacement — like mapping one status code to 'Yes' and another to 'No' in one dict. replace() applies every one of those mappings in a single call, which is both more concise and clearer about intent than chaining several separate replace() calls, one for each individual old-to-new substitution.

Exercises

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

View Solution

import pandas as pd

df = pd.DataFrame({"status": ["Y", "N", "Y", "N"]})
print(df.replace({"Y": "Yes", "N": "No"}))

Frequently Asked Questions

How would you replace several different values with different corresponding new values in a single call to replace()?▼

Related Functions

series-str-replacedf-fillnadf-astype