Skip to main content
`Ctrl`+`K`

# pandas.DataFrame.rename

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

  Rename columns or index labels.

  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 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 False

      This keyword is now ignored; changing its value will have no impact on the method.

      Deprecated since version 3.0.0: This keyword is ignored and will be removed in pandas 4.0. Since pandas 3.0, this method always returns a new object using a lazy copy mechanism that defers copies until necessary (Copy-on-Write). See the user guide on Copy-on-Write for more details.

    inplace bool, default False

      Whether to modify the DataFrame rather than creating a new one. If True then value of copy is ignored.

      Deprecated since version 3.1.0: This keyword is deprecated and will be removed in pandas 4.0. See PDEP-8 In-place methods in pandas for more details.

    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 KeyError when a dict-like mapper, index, or 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.

  Returns:
    DataFrame or None

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

  Raises:
    KeyError

      If any of the labels is not found in the selected axis and “errors=’raise’”.

  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:

      >>> 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:

      >>> 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:

      >>> df.index
      RangeIndex(start=0, stop=3, step=1)
      >>> df.rename(index=str).index
      Index(['0', '1', '2'], dtype='str')

      >>> 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:

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

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