# How to Use pandas dataframe map to Apply Functions Element-wise

> Learn how to use pandas dataframe map to apply functions element-wise transform DataFrame values using callables dictionaries or Series lookup tables with NaN handling.

- Repository: [pandas/pandas](https://github.com/pandas-dev/pandas)
- Tags: how-to-guide
- Published: 2026-02-14

---

**Use `DataFrame.map()` to transform every individual value in a pandas DataFrame by passing a callable function, dictionary, or Series lookup table, with optional `na_action='ignore'` to preserve NaN values.**

The `pandas dataframe map` method provides element-wise transformation capabilities for entire DataFrames in the pandas-dev/pandas repository. Unlike column-wise operations, this method touches each cell individually using the same underlying machinery as `Series.map`. Mastering this method allows you to perform complex data cleaning and transformation tasks with concise, readable code.

## Understanding the pandas dataframe map Method

According to the pandas source code in [`pandas/core/frame.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py) at line 14234, the `map()` method signature is:

```python
def map(self, func, na_action=None, **kwargs):
    """Apply a function element-wise to the DataFrame."""

```

The method delegates to the `Series.map` implementation found in [`pandas/core/series.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/series.py) at line 4649, ensuring consistent behavior across data structures. When you invoke `pandas dataframe map`, the operation returns a new DataFrame with identical shape and index/column labels, leaving the original data untouched.

## Mapper Types and Parameters

The `func` parameter accepts three distinct mapping strategies:

### Callable Functions

Pass any Python callable—functions, lambdas, or `np.vectorize`—to transform each element based on custom logic. The return value replaces the original element directly.

### Dictionary or Series Lookups

Provide a `dict`, `Series`, or array-like object to treat the mapper as a lookup table. The original value becomes the key, and the corresponding mapped value is inserted. Missing keys result in `NaN` values.

### The na_action Parameter

Set `na_action='ignore'` to skip existing `NaN` values during mapping. Without this parameter, the mapper attempts to process null values, which may raise errors or produce unexpected results depending on your callable.

## Practical Code Examples

The following examples demonstrate real-world usage patterns based on the pandas implementation:

### Example 1: Element-wise Type Transformation

```python
import pandas as pd
import numpy as np

df = pd.DataFrame({
    "A": [1, 2, 3],
    "B": ["cat", "dog", "mouse"],
    "C": [10.5, 20.2, 30.1]
})

def mapper(x):
    if isinstance(x, (int, float)):
        return x * x
    if isinstance(x, str):
        return x.upper()
    return x

df_mapped = df.map(mapper)
print(df_mapped)

```

Output:

```

     A      B      C
0    1    CAT  110.25
1    4    DOG  408.04
2    9  MOUSE  906.01

```

### Example 2: Dictionary Lookup for Code Replacement

```python
code_df = pd.DataFrame({
    "code": ["A", "B", "C", "A"],
    "value": [10, 20, 30, 40]
})
lookup = {"A": "Alpha", "B": "Beta", "C": "Gamma"}

code_df_mapped = code_df.map(lookup)
print(code_df_mapped)

```

Output:

```

       code  value
0    Alpha   10.0
1     Beta   20.0
2    Gamma   30.0
3    Alpha   40.0

```

Note that values missing from the lookup dictionary automatically convert to `NaN`.

### Example 3: Preserving NaN Values During Mapping

```python
df2 = pd.DataFrame({
    "X": [1, np.nan, 3],
    "Y": ["a", "b", np.nan]
})

df2_mapped = df2.map(
    lambda x: x * 10 if isinstance(x, (int, float)) else str(x).upper(),
    na_action='ignore'
)
print(df2_mapped)

```

Output:

```

      X    Y
0  10.0    A
1   NaN    B
2  30.0  NaN

```

## Performance Considerations

While `pandas dataframe map` provides intuitive syntax for element-wise operations, consider the performance characteristics documented in the source. Dictionary and Series lookups execute quickly, but heavy Python callables may bottleneck on large datasets. For performance-critical applications, prefer vectorized NumPy operations or `DataFrame.applymap` when appropriate.

## Summary

- `pandas dataframe map` applies transformations element-wise to every cell in a DataFrame.
- Accepts callables, dictionaries, or Series objects as mapping functions.
- Returns a new DataFrame with identical shape and labels, preserving the original data.
- Use `na_action='ignore'` to prevent processing of existing null values.
- Implementation resides in [`pandas/core/frame.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/frame.py) with shared logic from [`pandas/core/series.py`](https://github.com/pandas-dev/pandas/blob/main/pandas/core/series.py).

## Frequently Asked Questions

### What is the difference between map() and apply() in pandas?

`map()` operates on individual elements (scalar values), while `apply()` operates on entire columns or rows (Series objects). Use `map()` for cell-level transformations and `apply()` for aggregations or vectorized operations across an axis.

### Can I use map() on specific columns only?

No, `DataFrame.map()` applies to the entire DataFrame. To map specific columns, select the column to create a Series, use `Series.map()`, then assign back: `df['col'] = df['col'].map(func)`.

### How does map() handle missing keys in dictionary mappings?

When using a dictionary mapper, any value not present as a key returns `NaN`. This behavior ensures type consistency but requires comprehensive key coverage or post-processing to handle unmapped values.

### Is map() faster than applymap() for DataFrames?

Both methods provide similar element-wise functionality, but `map()` (introduced in newer pandas versions) leverages optimized internal machinery from `Series.map`. For simple lookups, both are comparable; for complex functions, vectorized NumPy operations typically outperform either method.