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 |
Table of contents
- The DataFrame.rename() function
- Rename a single column
- Rename multiple columns
- Rename columns in place
- Rename column using a function
- 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
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 tocolumns
. 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 aKeyError
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 throwsKeyError
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:
labels
: List of column names as an input.axis
: The axis to update. Setaxis=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)
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
Leave a Reply