Pandas · Module

df.rename

Rename a DataFrame’s column labels, index labels, or both with mappings or callables. Unmentioned labels stay unchanged by default, and the operation returns a new DataFrame unless inplace=True.

How it works

DataFrame.rename changes column labels, index labels, or both by applying a mapping or callable. Use index and columns keyword arguments to make the target axis explicit; by default, labels not mentioned remain unchanged and the original DataFrame is preserved.

Syntax

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

Parameters

Name	Type	Description
`mapper`	`dict, Series, callable, or None`	Mapping or callable applied to the selected axis; can be omitted when index or columns is supplied.
`index`	`dict, Series, callable, or None`	Mapping or callable for index labels.
`columns`	`dict, Series, callable, or None`	Mapping or callable for column labels.
`axis`	`int or str, optional`	Axis to rename when using mapper; accepts index/columns names or 0/1 equivalents.
`inplace`	`bool, default False`	Whether to modify the existing DataFrame rather than return a renamed copy.
`level`	`int or level name, optional`	For a MultiIndex, selects the level whose labels are renamed.
`errors`	`{‘ignore’, ‘raise’}, default ‘ignore’`	Whether missing mapping keys are ignored or raise an error.

Returns

DataFrame with the renamed axis labels, or None if inplace=True.

Key points

The method can target either axis independently or rename both in one call.
A mapping only changes labels it contains; all other labels retain their existing values.
Without in-place mutation, the result is a DataFrame; inplace=True changes the object and returns None.
The API supports explicit index/columns arguments as well as a mapper combined with axis.
A dictionary mapping is suitable when specific known labels need replacement.

Common mistakes

The resulting labels must form a one-to-one mapping; duplicate target labels are not valid.
With the default errors='ignore', mapping keys that are absent from the selected axis do not raise an exception.
Prefer index= or columns= over the positional mapper plus axis form, especially when code should be easy to review.

Example: Rename selected labels

import pandas as pd

df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
renamed = df.rename(columns={"A": "a"}, index={0: "first"})
print(renamed)

Creates a new DataFrame with selected column and index labels renamed.

When to use it

Standardize column names

A dataset uses source-system field names that should become readable application names.

Relabel index entries

Rows need business-friendly identifiers without changing their data values.

Rename one MultiIndex level

A MultiIndex contains labels that must be changed only within one level.

Interview questions

QWhat does DataFrame.rename do?

It renames index labels, column labels, or both. A dictionary or Series maps existing labels to new labels, while a callable can transform labels individually; omitted labels remain unchanged.

Follow-up: How do you ensure missing mapping keys fail loudly? Set errors='raise', which makes absent labels trigger an error instead of being ignored.

QHow do you rename columns and index labels?

Use df.rename(columns={'old': 'new'}) for columns and df.rename(index={old: new}) for index labels. The method returns a renamed DataFrame unless inplace=True.

Follow-up: Why prefer columns= and index= instead of mapper with axis? They identify the target axis directly and avoid ambiguity in maintenance and review.

QWhat is the effect of errors='ignore' versus errors='raise'?

The default errors='ignore' leaves labels not found in a mapping unchanged. Setting errors='raise' causes an exception when a mapping key is not present on the chosen axis.

Follow-up: What constraint applies to replacement labels? Function or dictionary values must define a one-to-one mapping, so duplicate target labels are not allowed.

DataFrame.rename_axis
DataFrame.set_axis
DataFrame.reindex

Source: DataFrame.rename. Checked 2026-10-15.