Being able to rename columns in your Pandas DataFrame is an incredibly common task. In particular, being able to label your DataFrame columns in a meaningful way is useful to communicate your data better. Similarly, you have inherited a dataset from someone and the columns are mislabeled. In all of these cases, being able to rename your DataFrame’s columns is a useful skill.
In this tutorial, you’ll learn how to rename Pandas DataFrame columns. You’ll learn how to use the Pandas .rename() method as well as other useful techniques. For example, you’ll learn how to add a prefix to every column name.
By the end of this tutorial, you’ll have learned the following:
- How to rename a single column or all columns in a Pandas DataFrame using the
.rename()method - How to use the
.columnsattribute to rename columns in creative ways, such as by adding a prefix or suffix, or by lowercasing all columns - How to replace or remove specific text or characters from all column names at once
- How to use mapper functions to rename Pandas DataFrame columns
Table of Contents
How to Rename Columns in a Pandas DataFrame
To rename columns in a Pandas DataFrame, you have two options: using the rename() method or the columns attribute. The .rename() method allows you to pass in existing labels and the ones you want to use. The .columns attribute allows you to specify a list of values to use as column labels.
Let’s look at the primary methods of renaming Pandas DataFrame columns in a bit more detail:
- The Pandas .rename() method allows you to rename DataFrame labels. In particular, you can pass in a mapping to rename column labels. This can either be a mapper function or a dictionary of column labels to use. This method is best when you want to relabel a single or a few columns.
- The Pandas .columns attribute allows you to pass in a list of values to use as the column names. This allows you to easily modify all column names by applying the same transformation to all column labels. This method is best when you want to rename all columns following the same type of transformation, such as lower-casing all column names or removing spaces.
Loading a Sample Pandas DataFrame
To follow along, let’s load a sample Pandas DataFrame. Feel free to copy and paste the code below into your favorite code editor. If you’re working with your own dataset – no problem! The results will, of course, vary.
# Loading a Sample Pandas DataFrame
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
print(df)
# Returns:
# Name Age Age Group Birth City Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe can see that we have a DataFrame with five different columns. Some of the columns are single words, while others are multiple words with spaces. Similarly, all of our column names are in title case, meaning that the first letter is capitalized.
Let’s dive into how to rename Pandas columns by first learning how to rename a single column.
How to Rename a Single Pandas DataFrame Column
To rename a single Pandas DataFrame column, we can use the Pandas .rename() method. The method, as the name implies, is used to rename labels in a DataFrame. Let’s take a quick look at how the method is written:
# Understanding the Pandas .rename() Method
import pandas as pd
df.rename(mapper=None, *, index=None, columns=None, axis=None, copy=None, inplace=False, level=None, errors='ignore')We can see that the function takes up to seven arguments. Some of these parameters are specific to renaming row (index) labels. Since we’re focusing on how to rename columns, let’s only focus on a subset of these.
In order to rename a single column in Pandas, we can use either the mapper= parameter or the columns= helper parameter. Because columns are along the first axis, if we want to use the mapper= parameter, we need to specify axis=1. This, however, is a bit more complicated, in my opinion, than using the columns= convenience parameter.
Let’s take a look at how we can use the columns= parameter to rename a Pandas column by name:
# Renaming a Single Column In a Pandas DataFrame
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(columns={'Birth City': 'City'})
print(df)
# Returns:
# Name Age Age Group City Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe can see that by passing a dictionary of column mappings into the columns= parameter, we were able to rename a single Pandas column. This is the equivalent of having written df = df.rename(mapper={'Birth City': 'City'}, axis=1). However, not only is this clear, but it’s also faster to type!
Renaming a Single Pandas DataFrame Column by Position
Now, say you didn’t know what the first column was called, but you knew you wanted to change its name to something specific. The df.columns attribute returns a list of all of the column labels in a Pandas DataFrame. Because of this, we can pass in the mapping of the first column.
For example, if we wanted to change the first column to be named 'id', we could write the following:
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(columns={df.columns[0]: 'id'})
print(df)
# Returns:
# id Age Age Group Birth City Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe can see that we were able to rename the first column of a DataFrame by using the .columns attribute. We’ll get back to using that attribute more in a minute. However, let’s now focus on how we can rename multiple columns at once.
How to Rename Multiple Pandas Columns with .rename()
Similar to renaming a single column in a DataFrame, we can use the .rename() method to rename multiple columns. In order to do this, we simply need to pass in a dictionary containing more key-value pairs.
Let’s see how we can rename multiple columns in a Pandas DataFrame with the .rename() method:
# Rename Multiple Columns with .rename()
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(columns={'Age Group': 'Group', 'Birth City': 'City'})
print(df)
# Returns:
# Name Age Group City Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe can see that we were able to rename multiple columns in one go. At this point, I’ll note that if a column doesn’t exist, Pandas won’t (by default) throw an error – though you can change this, as you’ll learn later.
Let’s now take a look at a way to rename multiple columns using a list comprehension.
How to Use List Comprehensions to Rename Pandas DataFrame Columns
In this section, you’ll learn how to use list comprehensions to rename Pandas columns. This can be helpful when you want to rename columns in a similar style. This could include removing spaces or changing all cases to lowercase.
For example, if your column names have spaces, it can be impossible to use dot notation to select columns. Similarly, since selecting columns is case-sensitive, having different casing in your columns can make selecting them more difficult.
Let’s take a look at an example where we want to remove all spaces from our column headers:
# Rename Columns Using a List Comprehension
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df.columns = [col.replace(' ', '_').lower() for col in df.columns]
print(df)
# Returns:
# name age age_group birth_city gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleLet’s break down what we’re doing in the code block above:
- We used a list comprehension to iterate over each column name in our DataFrame
- For each column label, we used the
.replace()string method to replace all spaces with underscores - We then also applied the
.lower()method to change the string to its lowercase equivalent
It’s important to note here that we’re not reassigning this list to the DataFrame, but rather to the df.columns attribute. Since the attribute represents the column labels, we can assign a list of values directly to that attribute to overwrite column names.
Using a Mapper Function to Rename Pandas Columns
The Pandas .rename() method also allows you to pass in a mapper function directly into the mapper= parameter. Rather than needing to pass in a dictionary of label mappings, you can apply the same mapping transformation to each column label.
Say we simply wanted to lowercase all of our columns, we could do this using a mapper function directly passed into the .rename() method:
# Using a Mapper Function to Rename DataFrame Columns
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(mapper=str.lower, axis='columns')
print(df)
# Returns:
# name age age_group birth_city gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe use axis='columns' to specify that we want to apply this transformation to the columns. Similarly, you could write: axis=1. We can see that this applied the transformation to all columns.
Keep in mind, because we’re using a string method, this will only work if your columns are all strings! If any of your columns are, say, just numbers, this method will raise a TypeError.
Using a Lambda Function to Rename Pandas Columns
You can also use custom lambda functions to pass in more complex transformations. This works in the same way as using a simple, built-in mapper function. However, it allows us to pass in custom transformations to our column names.
Let’s take a look at an example. If we wanted to use a lambda function to rename all of our columns by replacing spaces and lowercasing our characters, we could write:
# Using a Lambda Function to Rename Columns
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(mapper=lambda x: x.replace(' ', '_').lower(), axis=1)
print(df)
# Returns:
# name age age_group birth_city gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleWe use axis=1 to specify that we want to apply this transformation to the columns. Similarly, you could write: axis='columns'.
Renaming Pandas DataFrame Columns In Place
You may have noticed that for all of our examples using the .rename() method, we have reassigned the DataFrame to itself. We can avoid having to do this by using the boolean inplace= parameter in our method call. Let’s use our previous example to illustrate this:
# Renaming DataFrame Columns In Place
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df.rename(mapper=lambda x: x.replace(' ', '_').lower(), axis=1, inplace=True)
print(df)
# Returns:
# name age age_group birth_city gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleIn the following section, you’ll learn how to raise errors when using the pd.rename() method.
Raising Errors While Renaming Pandas Columns
By default, the .rename() method will not raise any errors when you include a column that doesn’t exist. This can lead to unexpected errors when you assume that a column has been renamed when it hasn’t.
Let’s see this in action by attempting to rename a column that doesn’t exist:
# Raising an Error When Renaming Columns
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.rename(columns={'some silly name': 'column1'}, errors='raise')
print(df)
# Returns:
# KeyError: "['some silly name'] not found in axis"We can see that by using the errors= parameter, that we can force Python to raise errors when a column label doesn’t exist.
Renaming Multi-index Pandas Columns
The .rename() method also includes an argument to specify which level of a multi-index you want to rename. A common occurrence of multi-index Pandas DataFrames is when working with pivot tables. Let’s take a look at an example. Say we create a Pandas pivot table and only want to rename a column in the first layer.
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
pivot = pd.pivot_table(data=df, columns=['Gender', 'Age Group'], values='Age', aggfunc='count')
pivot = pivot.rename(columns={'Male': 'male'}, level=0)
print(pivot)
# Returns:
# Gender Female male
# Age Group 18-35 35-50 35-50 65+
# Age 1 1 1 1In the example above, we created a multi-index Pandas DataFrame. The first layer (layer 0) contains the values from our Gender column. By specifying that we want to only use level 0, we can target column labels only in that level. To learn more about Pandas pivot tables, check out my comprehensive guide to Pandas pivot tables.
Add a Prefix or Suffix to Pandas DataFrame Columns
We can also add a prefix or a suffix to all Pandas DataFrame columns by using dedicated methods:
.add_prefix()will add a prefix to each DataFrame column, and.add_suffix()will add a suffix to each DataFrame column
Let’s see how we can use these methods to add a prefix to our DataFrame’s columns:
# Adding a Prefix to Our DataFrame Columns
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df = df.add_prefix('prefix_')
print(df)
# Returns:
# prefix_Name prefix_Age prefix_Age Group prefix_Birth City prefix_Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleAdding a suffix would work in the same way, though we would use the .add_suffix() method instead.
Similarly, if we only want to add a suffix to specific columns, we can use a list comprehension. For example, if we wanted to add a suffix to columns that have the word age in them, we can use the following code:
# Adding a Suffix Conditionally
import pandas as pd
df = pd.DataFrame.from_dict({
'Name': ['Jane', 'Melissa', 'John', 'Matt'],
'Age': [23, 45, 35, 64],
'Age Group': ['18-35', '35-50', '35-50', '65+'],
'Birth City': ['London', 'Paris', 'Toronto', 'Atlanta'],
'Gender': ['Female', 'Female', 'Male', 'Male']})
df.columns = [col+'_suffix' if 'Age' in col else col for col in df.columns]
print(df)
# Returns:
# Name Age_suffix Age Group_suffix Birth City Gender
# 0 Jane 23 18-35 London Female
# 1 Melissa 45 35-50 Paris Female
# 2 John 35 35-50 Toronto Male
# 3 Matt 64 65+ Atlanta MaleIn the example above, we used a list comprehension to apply a transformation conditionally. This allowed us to check for a condition. If the condition was met (in this case, if ‘Age’ was in the column name) then the suffix is added. Otherwise, the column name is left unchanged.
Conclusion
In this post, you learned about the different ways to rename columns in a Pandas DataFrame. You first learned the two main methods for renaming DataFrame columns: using the Pandas .rename() method and using the .columns attribute.
From there, you learned how to rename a single column, both by name and by its position. From there, you learned how to rename multiple columns. You learned how to do this using the .rename() method, as well as list comprehensions. From there, you learned about using mapper functions, both built-in functions, as well as custom lambda functions. Finally, you learned how to rename DataFrames in place, raise errors when columns don’t exist, and how to work with levels in multi-index DataFrames.
Additional Resources
To learn more about related topics, check out the resources below: