Rename columns in Pandas DataFrame

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

mapper: It is used to specify new names for columns. It takes a Python dictionary or function as input.
columns: It is used to specify new names for columns. It takes to dictionary or function as input.
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.
copy: It allows the copy of underlying data. It is a boolean flag with default True.
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.
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.
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.

Syntax:

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

Example:

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

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)

    name  age  marks
  Joe   20  85.10
  Nat   21  77.80
Harry   19  91.54
    name  age  percentage
  Joe   20       85.10
  Nat   21       77.80
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("Columns before renaming\n", 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("\nColumns after renaming\n", student_df.columns.values)

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

Columns after renaming
 ['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.

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)

['name' 'age' 'marks']
['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.

Example

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)

['name' 'age' 'marks']
['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)

['#name' '#age' '#marks']
['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']

[' name ' ' age   ' 'marks  ']
['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)

['name' 'age' 'marks']
['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])

df.columns[2]: marks
df.columns[2]: percentage

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"

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
<ipython-input-10-782dbd1412fe> in <module>
      5 student_df = pd.DataFrame(student_dict)
      6 
----> 7 student_df.rename(columns={'unknownCol': "a"}, inplace=True, errors='raise')
      8 print(student_df)
      9 

C:\ProgramData\Anaconda3\lib\site-packages\pandas\util\_decorators.py in wrapper(*args, **kwargs)
    310         @wraps(func)
    311         def wrapper(*args, **kwargs) -> Callable[..., Any]:
--> 312             return func(*args, **kwargs)
    313 
    314         kind = inspect.Parameter.POSITIONAL_OR_KEYWORD

C:\ProgramData\Anaconda3\lib\site-packages\pandas\core\frame.py in rename(self, mapper, index, columns, axis, copy, inplace, level, errors)
   4439         4  3  6
   4440         """
-> 4441         return super().rename(
   4442             mapper=mapper,
   4443             index=index,

C:\ProgramData\Anaconda3\lib\site-packages\pandas\core\generic.py in rename(self, mapper, index, columns, axis, copy, inplace, level, errors)
   1053                         if indexer[index] == -1
   1054                     ]
-> 1055                     raise KeyError(f"{missing_labels} not found in axis")
   1056 
   1057             new_index = ax._transform_index(f, level)

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)

['name' 'age' 'marks']
['$_name_$' '$_age_$' '$_marks_$']

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:

labels: List of column names as an input.
axis: The axis to update. Set axis=1 rename column headers. The default value is 0. (i.e., rename row index)
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)

['name' 'age' 'marks']
['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)

  Class A        Class B       
     Name  Marks    Name  Marks
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55
  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)

  Class A        Class B       
     Name  Marks    Name  Marks
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55
  Class A        Class B       
     NAME  MARKS    NAME  MARKS
0     Joe  85.10     Nat  77.80
1   Harry  91.54     Sam  68.55

Rename columns in Pandas DataFrame

Contents

Rename columns in Pandas DataFrame#

The DataFrame.rename() function#

Rename a single column#

Rename multiple columns#

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

Rename columns in place#

Rename column using a function#

Use lambda expressions to rename#

Rename columns by removing leading and trailing spaces#

Rename all columns with a list#

Rename column by index position#

Raise error while renaming a column#

Rename column by adding prefix/suffix#

Rename column using DataFrame.set_axis()#

Rename column in multi-index DataFrame#

Rename columns in all levels#

Rename columns in defined level#

The `DataFrame.rename()` function#

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

Rename column using `DataFrame.set_axis()`#