Rename columns in Pandas DataFrame

In Python, renaming columns label is useful when working with a pandas Dataframe with no column names or want to rename a specific column’s names. This article covers all the cases of renaming column labels of the pandas DataFrame.

You will learn the following functions available in the pandas to rename columns of a simple DataFrame as well as multi-index DataFrame.

Function	Description
df.rename(columns={'old': 'new'})	Rename column with label ‘old’ to ‘new’
df.rename(index={0: 'I'})	Rename row index 0 (zero) to ‘I’
df.add_prefix('$_')	Rename all column labels by adding a prefix
df.add_suffix('_$')	Rename all column labels by adding a suffix
df.set_axis(['a', 'b', 'c'], axis=1)	Reassign column names to new names
df.rename_axis("Sr.No.")	Assign a name to column header or row index header

The DataFrame.rename() function

This is the most widely used pandas function for renaming columns and row indexes. Let’s see the syntax of it before moving to examples.

Syntax:

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

Parameters:

1. mapper: It is used to specify new names for columns. It takes a Python dictionary or function as input.
2. columns: It is used to specify new names for columns. It takes to dictionary or function as input.
3. axis: Alternative to columns. It is used to specify the axis to apply with the mapper. Column axis represented as 1 or ‘columns‘. Default 0.
4. copy: It allows the copy of underlying data. It is a boolean flag with default True.
5. inplace: It is used to specify whether to return a new copy of a DataFrame or update existing ones. It is a boolean flag with default False.
6. level: In the case of a multi-index DataFrame, only rename labels in the specified level. It takes int or level name as input. The default value is None.
7. errors: It is either ‘ignore’ or ‘raise’. Default is ‘ignore’. If ‘raise’, raise a KeyError if the columns or index are not present. If ‘ignore’, existing keys will be renamed and extra keys will be ignored.

Return value:

• It returns a DataFrame with the renamed column and row labels or None if inplace=True.
• Also, It raises KeyError If any of the labels are not found in the selected axis when errors='raise'

Rename a single column

Sometimes it is required to rename the single or specific column names only.  Use the column parameter of DataFrame.rename() function and pass the columns to be renamed.

Use the following syntax code to rename the column.

df.rename(columns={'column_current_name': 'new_name'})

Now, let’s see how to rename the column “marks” to ‘percentage‘.

Example

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

# Create DataFrame from dict
student_df = pd.DataFrame(student_dict)
# before rename
print(student_df)

# after rename column
student_df = student_df.rename(columns={'marks': "percentage"})
print(student_df)

Output:

    name  age  marks
0    Joe   20  85.10
1    Nat   21  77.80
2  Harry   19  91.54

    name  age  percentage
0    Joe   20       85.10
1    Nat   21       77.80
2  Harry   19       91.54

Rename multiple columns

Use any of the following two parameters of a DataFrame.rename() to rename multiple or all column labels at once.

• Use the column parameter and pass all column names you want to rename as a dictionary (old column name as a key and new column name as a value).
• Set the axis=1 and pass column names you want to rename as a dictionary

Example

Let’s see how to rename all three columns of a dataframe.

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
# column names before rename
print(student_df.columns.values)

# rename all columns using mapping convention
student_df = student_df.rename(columns={'name': "a", 'age': "b", 'marks': "c"})
# after rename
print(student_df.columns.values)

Output:

Columns before renaming
['name' 'age' 'marks']

After rename
['a' 'b' 'c']

Using rename with axis='columns' or axis=1

Let’s see how to rename using the axis-style convention. This is a new approach.( This approach makes this method match the rest of the pandas API) .

Use the axis parameter of a df.rename() to rename columns and row index. The axis can be a row or column. The column axis represented as 1 or ‘columns’.

Set axis=1 and pass column names you want to rename as a dictionary (Key-Value pairs).

Example

Let’s see how to rename all three columns.

student_df = student_df.rename({'name': "a", 'age': "b", 'marks': "c"}, axis='columns')
# alternative both produces same result
student_df = student_df.rename({'name': "a", 'age': "b", 'marks': "c"}, axis=1)

Rename columns in place

In the above examples, whenever we executed rename operations, pandas created a new copy of DataFrame because the modification is not-in place.

Specify inplace=True to rename the existing DataFrame rather than creating a copy of it.

• If the inplace=True then it updates the existing DataFrame and does not return anything.
• If the inplace=False then it creates a new DataFrame with updated changes and returns it.

Note: You don’t need to assign the result back to a variable as we are performing modifications in place.

Example

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
# column names before rename
print(student_df.columns.values)

# rename columns inplace
student_df.rename(columns={'name': "a"}, inplace=True)
print(student_df.columns.values)

Output:

Before rename
['name' 'age' 'marks']

After rename
['a' 'age' 'marks']

Rename column using a function

We can also use the function to rename column labels by applying some logic to it. We can use built-in as well as user-defined functions to rename columns.

In the below example, we rename all column names to UPPER CASE using the string function str.upper.

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

# Create DataFrame from dict
student_df = pd.DataFrame(student_dict)
# before rename
print(student_df.columns.values)

# rename column names using function
student_df.rename(columns=str.upper, inplace=True)
# after rename
print(student_df.columns.values)

Output:

Before applying function to rename
['name' 'age' 'marks']

After rename
['NAME' 'AGE' 'MARKS']

Use lambda expressions to rename

Also, you can use lambda expressions to rename column label or row index. Let’s see how to remove the first character from each column label using lambda.

import pandas as pd

student_dict = {"#name": ["Joe", "Nat", "Harry"], "#age": [20, 21, 19], "#marks": [85.10, 77.80, 91.54]}

# Create DataFrame from dict
student_df = pd.DataFrame(student_dict)
# before rename
print(student_df.columns.values)

# remove first character of column names
student_df.rename(columns=lambda x: x[1:], inplace=True)
# after rename
print(student_df.columns.values)

Output:

Columns Before rename
['#name' '#age' '#marks']

After rename
['name' 'age' 'marks']

Rename columns by removing leading and trailing spaces

Use lambda expression to rename columns by removing leading and trailing spaces from the column names

Example

import pandas as pd

student_dict = {" name ": ["Joe", "Nat", "Harry"], " age   ": [20, 21, 19], "marks  ": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
print(student_df.columns.values)
# output [' name ' ' age   ' 'marks  ']

# remove leading and trailing space from column names
student_df.rename(lambda x: x.strip(), axis='columns', inplace=True)
print(student_df.columns.values)
# Output ['name' 'age' 'marks']

Rename all columns with a list

Suppose we have a list of column names that we need to use to rename the existing DataFrame. In that case, we can pass the list of column labels to a DataFrame.columns  attributes as shown in the below example.

It will replace the existing names with the new names in the order you provide.

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
# before rename
print(student_df.columns.values)

# rename column with list
student_df.columns = ['stud_name', 'stud_age', 'stud_marks']
# after rename
print(student_df.columns.values)

Output:

Before renaming labels
['name' 'age' 'marks']

After rename
['stud_name' 'stud_age' 'stud_marks']

Rename column by index position

If there is a case where we want to rename the first column or the last column in the DataFrame, but we do not know the column name still we can rename the column using a DataFrame.columns attribute.

Note: Column index starts from 0 (zero) and it goes till the last column whose index value will be len(df.columns)-1 .

Example

In the below example, we are renaming the second column of the DataFrame using  df.columns[1]

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
print("df.columns[2]:", student_df.columns[2])

# rename column present at index 2
student_df.rename(columns={student_df.columns[2]: 'percentage'}, inplace=True)
print("df.columns[2]:", student_df.columns[2])

Output:

Column before renaming
df.columns[2]: marks

After rename
df.columns[2]: percentage

You can also rename multiple columns using the index number.

# rename multiple columns using index number
student_df.rename(columns={student_df.columns[0]: 'new_name', student_df.columns[1]: 'new_age'}, inplace=True)
print(student_df.columns.values)

Raise error while renaming a column

By default, The DataFrame.rename() doesn’t throw any error if column names you tried to rename doesn’t exist in the dataset.

Do you want to throw an error in such cases?

If yes, then use the errors parameter of DataFrame.rename().

• Set errors='raised' to throws KeyError for the unknown columns
• Set errors='ignore' to not throw any errors.

Note:

• If the new name mapping is not provided for some column label then it isn’t renamed.
• Extra labels in the mapping don’t throw an error.

Example

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)

student_df.rename(columns={'unknownCol': "a"}, inplace=True, errors='raise')
print(student_df)

Output:

KeyError: "['unknownCol'] not found in axis"

Rename column by adding prefix/suffix

We can rename the DataFrame columns using DataFrame.add_prefix() and DataFrame.add_suffix() functions. It appends the input string as a prefix or suffix to the column names respectively.

Note: These functions are only applicable to column labels and not row index of the DataFrame.

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
print(student_df.columns.values)

# add prefix and suffix to column names
student_df = student_df.add_prefix("$_")
student_df = student_df.add_suffix("_$")

print(student_df.columns.values)

Output:

Before adding prefix and suffix:
['name' 'age' 'marks']

After adding prefix and suffix:
['$_name_

Rename column using DataFrame.set_axis()

Use the set_axis() method you to rename all the index or column labels with a list. Using this function we can reassign column headers or row index of the DataFrame.

This function is useful when working with a data set with no column names.

Syntax:

DataFrame.set_axis(labels, axis=0, inplace=False)

Parameters:

1. labels: List of column names as an input.
2. axis: The axis to update. Set axis=1 rename column headers. The default value is 0. (i.e., rename row index)
3. inplace: It is used to decide whether to return a new DataFrame instance or rename the existing one. It is a boolean flag with the default False. If it is True then it renames the existing DataFrame rather than creating a copy.

Returns:

It returns an object of type DataFrame else None if inplace=True.

Note: Supply a list to the set_axis() method that is equal in length to the number of columns otherwise you will get an error.

Example:

import pandas as pd

student_dict = {"name": ["Joe", "Nat", "Harry"], "age": [20, 21, 19], "marks": [85.10, 77.80, 91.54]}

student_df = pd.DataFrame(student_dict)
print(student_df.columns.values)

# reassign column headers
student_df.set_axis(['new_name', 'new_age', 'new_marks'], axis='columns', inplace=True)
print(student_df.columns.values)

Output:

Before rename
['name' 'age' 'marks']
After rename
['new_name' 'new_age' 'new_marks']

Rename column in multi-index DataFrame

Pandas DataFrame can have single or multiple rows as column labels, i.e., a header to identify the columns. DataFrame with multiple headers is called a multi-index DataFrame.

The below diagram shows the multi-index DataFrame where header levels start with 0.

Rename columns in all levels

We can apply DataFrame.rename() function on multi-index DataFrame.

In the below example, we use df.rename(columns={'old_col':'new_col'}) which rename the column labels in all the levels of multi-index DataFrame.

import pandas as pd

# create column header
col = pd.MultiIndex.from_arrays([['Class A', 'Class A', 'Class B', 'Class B'],
                                 ['Name', 'Marks', 'Name', 'Marks']])
# create dataframe from 2darray
student_df = pd.DataFrame([['Joe', '85.10', 'Nat', '77.80'], ['Harry', '91.54', 'Sam', '68.55']], columns=col)
print(student_df)

# rename column label
student_df = student_df.rename(columns={'Name': 'SName'})
print(student_df)

Output:

Before rename:
       Class A        Class B       
     Name  Marks    Name  Marks
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55

After rename:
       Class A        Class B       
    SName  Marks   SName  Marks
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55

Rename columns in defined level

It is the case when we have the same column labels in multiple levels of the multi-index DataFrame. But, we need to rename the column in a selected level only. Or we want to rename column labels of a particular level only in such cases we can use the level parameter of DataFrame.rename().

This parameter is used to specify the level name or level index where we need to rename the columns.

Example

In the below example, we rename the column label of only level 1 to the upper case using the string function columns=str.upper.

import pandas as pd

# create column header
col = pd.MultiIndex.from_arrays([['Class A', 'Class A', 'Class B', 'Class B'],
                                 ['Name', 'Marks', 'Name', 'Marks']])
# create dataframe from 2darray
student_df = pd.DataFrame([['Joe', '85.10', 'Nat', '77.80'], ['Harry', '91.54', 'Sam', '68.55']], columns=col)
print(student_df)

# rename column label in level 1
student_df = student_df.rename(columns=str.upper, level=1)
print(student_df)

Output:

Before rename:
       Class A        Class B       
     Name  Marks    Name  Marks
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55

After rename:
       Class A        Class B       
     NAME  MARKS    NAME  MARKS
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55