How to Rename Specific Columns in Pandas: DataFrame.rename() Explained

Use DataFrame.rename() with the columns parameter, passing either a dictionary mapping old names to new names or a callable function that transforms each label, to rename specific columns in a pandas DataFrame.

Renaming specific columns is a fundamental data manipulation task in the pandas library. According to the pandas-dev/pandas source code, column names are stored in the Index object that labels the columns of a DataFrame, and the primary method for modifying these labels is DataFrame.rename() implemented in pandas/core/frame.py. This method provides a flexible, dictionary-based interface for mapping existing column names to new ones without affecting untouched columns.

Understanding the DataFrame.rename() Method

In pandas/core/frame.py, the DataFrame.rename() method is defined with the following signature:

DataFrame.rename(mapper=None, *, index=None, columns=None, axis=None,
                copy=True, inplace=False, level=None, errors='ignore')

Key parameters for renaming specific columns include:

• columns – A dict-like or callable that maps old column names to new ones.
• inplace – If True, the operation modifies the original object; otherwise a new DataFrame is returned.
• level – Useful when the columns have a MultiIndex and you need to target a specific level.

Internally, DataFrame.rename forwards the mapping to the underlying column Index by calling Index.rename (see pandas/core/indexes/base.py line 2005). The Index.rename method creates a new Index with the supplied name mapping while preserving the original order of the remaining labels.

Renaming Specific Columns with a Dictionary

To rename specific columns in pandas, pass a dictionary to the columns parameter where keys are existing column names and values are the desired new names:

import pandas as pd

df = pd.DataFrame(
    {
        "first_name": ["Alice", "Bob"],
        "last_name": ["Smith", "Jones"],
        "age": [25, 30],
    }
)

# Rename specific columns using a dict

df_renamed = df.rename(columns={"first_name": "First", "last_name": "Last"})
print(df_renamed.columns)

# Index(['First', 'Last', 'age'], dtype='object')

Only the keys present in the dictionary are modified; all other column names remain unchanged. This makes DataFrame.rename() ideal for targeted updates without listing every column in your dataset.

Transforming Column Names with Callable Functions

You can also rename columns by passing a callable function to the columns parameter. The function is applied to every column label:

# Rename columns with a callable (make all names upper-case)

df_upper = df.rename(columns=str.upper)
print(df_upper.columns)

# Index(['FIRST_NAME', 'LAST_NAME', 'AGE'], dtype='object')

This approach works with any function that accepts a string and returns a string, such as lambda x: x.replace('_', '') to remove underscores or custom formatting functions.

In-Place Renaming vs. Returning a New Copy

By default, DataFrame.rename() returns a new DataFrame and leaves the original unchanged. To modify the existing DataFrame directly, set inplace=True:

# In-place renaming (no new DataFrame is created)

df.rename(columns={"age": "years"}, inplace=True)
print(df.columns)

# Index(['first_name', 'last_name', 'years'], dtype='object')

When inplace=False (the default), the copy parameter controls whether data is copied; when inplace=True, the operation avoids creating a new object and mutates the existing frame.

Renaming MultiIndex Columns

When working with hierarchical column indexes, use the level parameter to target specific levels of the MultiIndex:

cols = pd.MultiIndex.from_product([["A", "B"], ["x", "y"]])
df_multi = pd.DataFrame([[1, 2, 3, 4]], columns=cols)

# Rename the first level from 'A'/'B' to 'Group1'/'Group2'

df_multi = df_multi.rename(columns=lambda x: x.replace({"A": "Group1", "B": "Group2"}), level=0)
print(df_multi.columns)

# MultiIndex([('Group1', 'x'), ('Group1', 'y'), ('Group2', 'x'), ('Group2', 'y')],

#            )

The level parameter accepts either the integer position or the name of the level you want to modify.

Renaming the Column Axis Name (Metadata)

As implemented in pandas/core/generic.py, use rename_axis to change the name of the column axis (the metadata label for the axis) rather than the individual column labels themselves:

df.rename_axis("features", axis="columns", inplace=True)
print(df.axes[1].name)

# features

This changes the axis name property, not the column headers. Use rename() for changing actual column values and rename_axis() for changing axis metadata.

Summary

• Use DataFrame.rename(columns={...}) to map specific old column names to new ones without affecting other columns.
• Internal implementation delegates to Index.rename in pandas/core/indexes/base.py to preserve index order and integrity.
• In-place operations are available via inplace=True, which modifies the original object instead of returning a copy.
• Callable functions like str.upper or lambdas can transform column names when passed to the columns parameter.
• MultiIndex support requires the level parameter to target specific hierarchical levels.
• Axis metadata is modified separately using rename_axis from pandas/core/generic.py, not through rename.

Frequently Asked Questions

What is the difference between rename() and rename_axis() in pandas?

DataFrame.rename() changes the actual labels of the index or columns (the values you see in df.columns), while DataFrame.rename_axis() changes the name of the axis itself (the metadata describing what the index or columns represent, accessible via df.axes[1].name). For column renaming tasks, use rename() to change headers like "A" to "B", and rename_axis() only when you need to change the label describing the column axis.

Does DataFrame.rename() modify the DataFrame in-place or return a new copy?

By default, DataFrame.rename() returns a new DataFrame with renamed columns, leaving the original df unchanged. Set inplace=True to modify the existing object directly without creating a copy. This behavior is defined in pandas/core/frame.py and is consistent across the pandas API for mutation operations.

How do I rename columns using a function instead of a dictionary in pandas?

Pass any callable function to the columns parameter of DataFrame.rename(). For example, use df.rename(columns=str.upper) to convert all column names to uppercase, or pass a lambda like df.rename(columns=lambda x: x.replace('_', '')) to remove underscores. The function is applied to every column label in the Index.

Can I rename specific columns in a MultiIndex DataFrame?

Yes. Use the level parameter in DataFrame.rename() to target a specific level of a hierarchical column index. For example, df.rename(columns=lambda x: x.replace('old', 'new'), level=0) only renames labels in the first level of the MultiIndex, leaving other levels untouched. This is essential when working with complex datasets where column names are organized hierarchically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}