rename(self, mapper: 'Renamer | None' = None, *, index: 'Renamer | None' = None, columns: 'Renamer | None' = None, axis: 'Axis | None' = None, copy: 'bool' = True, inplace: 'bool' = False, level: 'Level | None' = None, errors: 'str' = 'ignore') -> 'DataFrame | None'

Function / dict values must be unique (1-to-1). Labels not contained in a dict / Series will be left as-is. Extra labels listed don't throw an error.

See the user guide <basics.rename> for more.

Parameters

mapper : dict-like or function

Dict-like or function transformations to apply to that axis' values. Use either mapper and axis to specify the axis to target with mapper , or index and columns .

index : dict-like or function

Alternative to specifying axis ( mapper, axis=0 is equivalent to index=mapper ).

columns : dict-like or function

Alternative to specifying axis ( mapper, axis=1 is equivalent to columns=mapper ).

axis : {0 or 'index', 1 or 'columns'}, default 0

Axis to target with mapper . Can be either the axis name ('index', 'columns') or number (0, 1). The default is 'index'.

copy : bool, default True

Also copy underlying data.

inplace : bool, default False

Whether to return a new DataFrame. If True then value of copy is ignored.

level : int or level name, default None

In case of a MultiIndex, only rename labels in the specified level.

errors : {'ignore', 'raise'}, default 'ignore'

If 'raise', raise a :None:None:`KeyError` when a dict-like mapper , :None:None:`index`, or :None:None:`columns` contains labels that are not present in the Index being transformed. If 'ignore', existing keys will be renamed and extra keys will be ignored.

Raises

KeyError

If any of the labels is not found in the selected axis and "errors='raise'".

Returns

DataFrame or None

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

Alter axes labels.

See Also

DataFrame.rename_axis

Set the name of the axis.

Examples

DataFrame.rename supports two calling conventions

• (index=index_mapper, columns=columns_mapper, ...)

• (mapper, axis={'index', 'columns'}, ...)

We highly recommend using keyword arguments to clarify your intent.

Rename columns using a mapping:

This example is valid syntax, but we were not able to check execution

>>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
... df.rename(columns={"A": "a", "B": "c"})
   a  c
0  1  4
1  2  5
2  3  6

Rename index using a mapping:

This example is valid syntax, but we were not able to check execution

>>> df.rename(index={0: "x", 1: "y", 2: "z"})
   A  B
x  1  4
y  2  5
z  3  6

Cast index labels to a different type:

This example is valid syntax, but we were not able to check execution

>>> df.index
RangeIndex(start=0, stop=3, step=1)

This example is valid syntax, but we were not able to check execution

>>> df.rename(index=str).index
Index(['0', '1', '2'], dtype='object')

This example is valid syntax, but we were not able to check execution

>>> df.rename(columns={"A": "a", "B": "b", "C": "c"}, errors="raise")
Traceback (most recent call last):
KeyError: ['C'] not found in axis

Using axis-style parameters:

This example is valid syntax, but we were not able to check execution

>>> df.rename(str.lower, axis='columns')
   a  b
0  1  4
1  2  5
2  3  6

This example is valid syntax, but we were not able to check execution

>>> df.rename({1: 2, 2: 4}, axis='index')
   A  B
0  1  4
2  2  5
4  3  6

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

pandas.core.generic.NDFrame.rename_axis pandas.core.generic.NDFrame._set_axis_name pandas.core.series.Series.rename

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: /pandas/core/frame.py#4964
type: <class 'function'>
Commit: