Pandas Renaming and Replacing
last modified November 17, 2026 Python 3.15
Data rarely arrives with perfect names or perfectly clean values. A column may be called old_a when you want a, or a city may be spelled two different ways. Pandas keeps these two jobs separate: rename changes labels — the names of rows and columns — while replace changes the actual values stored in the table.
Both operations normally return a new object rather than modifying the original, so they can be chained together one after another. All examples below were verified with pandas 3.1.1.
Renaming columns
A label is the name attached to a row or column. The rename method takes a dictionary that maps old labels to new ones. With columns=, only column labels are touched and every cell keeps its value.
import pandas as pd
df = pd.DataFrame({'old_a': [1, 2], 'old_b': [3, 4]})
print(df.rename(columns={'old_a': 'a', 'old_b': 'b'}))
The dictionary has two entries, so both headers change from old_a/old_b to a/b. Any column not mentioned in the dictionary would keep its old name.
$ python rename_columns.py a b 0 1 3 1 2 4
Renaming index labels
The index is the set of row labels. Passing index= to rename changes those labels instead of the column headers. Just as with columns, omitted labels stay as they were — here the middle label b is untouched.
import pandas as pd
df = pd.DataFrame({'value': [10, 20, 30]}, index=['a', 'b', 'c'])
print(df.rename(index={'a': 'first', 'c': 'last'}))
The two renamed labels, first and last, appear in the index, while b is unchanged. The values 10, 20 and 30 are not affected.
$ python rename_index.py
value
first 10
b 20
last 30
Using mapper and axis
mapper is the general form of the renaming argument: a function or dictionary applied to every label along one axis. The axis parameter says which labels to apply it to — 'columns' for column headers or 'index' for row labels. A function is handy when the new names follow a rule, such as making everything uppercase.
import pandas as pd
df = pd.DataFrame({'old_a': [1, 2], 'old_b': [3, 4]})
print("axis='columns':")
print(df.rename(mapper=str.upper, axis='columns'))
print()
df2 = pd.DataFrame({'v': [1, 2]}, index=['x', 'y'])
print("axis='index':")
print(df2.rename(mapper=str.upper, axis='index'))
The built-in str.upper function turns old_a and old_b into OLD_A and OLD_B. Applied to the index of the second frame, it turns the row labels x and y into X and Y. A dictionary could be used in exactly the same way.
$ python rename_mapper.py axis='columns': OLD_A OLD_B 0 1 3 1 2 4 axis='index': v X 1 Y 2
Assigning all labels at once
When every column needs a new name, assigning directly to df.columns is shorter than building a dictionary for rename. The right-hand side must be a sequence with exactly one entry per column, because the assignment replaces the whole set of labels.
import pandas as pd
df = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
df.columns = ['x', 'y']
print(df)
Both headers are replaced by x and y. The same trick works with df.index for row labels. The difference from rename is that assignment is all-or-nothing: a list of the wrong length raises an error, whereas rename lets you change just a few labels.
$ python columns_assignment.py x y 0 1 3 1 2 4
Replacing values with replace
Where rename changes labels, replace changes the values inside the table. Given a single scalar — one plain value — it swaps every occurrence of that value for the new one. Given a dictionary, it performs several substitutions at once, mapping each old value to its replacement.
import pandas as pd
df = pd.DataFrame({
'city': ['London', 'Paris', 'London', 'Rome'],
'code': [1, 2, 1, 3]
})
print("scalar replace:")
print(df.replace('London', 'LON'))
print()
print("dict replace:")
print(df.replace({'London': 'LON', 'Rome': 'ROM'}))
The scalar form changes every London to LON. The dictionary form does that and also changes Rome to ROM. Both forms search the whole DataFrame, including numeric columns if a matching value appeared there.
$ python replace.py
scalar replace:
city code
0 LON 1
1 Paris 2
2 LON 1
3 Rome 3
dict replace:
city code
0 LON 1
1 Paris 2
2 LON 1
3 ROM 3
Pattern-based replacement
A regular expression, or regex, is a small pattern language for matching text. Setting regex=True tells replace to interpret the old value as a pattern rather than a literal string. In the pattern 'Lon.*', the dot with the star means “any characters after Lon”.
import pandas as pd
df = pd.DataFrame({
'city': ['London', 'Paris', 'London', 'Rome'],
'code': [1, 2, 1, 3]
})
print(df.replace('Lon.*', 'LON', regex=True))
Both London entries match the pattern and become LON. Paris and Rome do not match and are left alone. Without regex=True, Pandas would look for the literal text Lon.* and replace nothing.
$ python replace_regex.py
city code
0 LON 1
1 Paris 2
2 LON 1
3 Rome 3
Substituting values with Series.map
map is a Series method that applies a dictionary or function to each value. When the dictionary has no entry for a value, the result is NaN — the marker Pandas uses for a missing result. It is a good choice when you are working with a single column rather than a whole DataFrame.
import pandas as pd
s = pd.Series(['cat', 'dog', 'cat', 'bird'])
translations = {'cat': 'feline', 'dog': 'canine'}
print(s.map(translations))
Cats and dogs are translated to feline and canine. The bird has no entry in the dictionary, so its output is NaN. This is a key difference from replace: replace leaves unmatched values untouched, while map turns them into missing values.
$ python series_map.py 0 feline 1 canine 2 feline 3 NaN dtype: str
Copies, inplace and chaining
By default these methods return a new object and leave the original alone. Because each call returns a DataFrame or Series, calls can be chained with dots: rename, then replace, then whatever comes next. You can also store the result with a normal assignment.
import pandas as pd
df = pd.DataFrame({'old': [1, 2, 3]})
result = df.rename(columns={'old': 'new'}).replace(1, 100)
print("chained result:")
print(result)
print()
print("original unchanged:")
print(df)
print()
assigned = df.rename(columns={'old': 'new'})
print("after assignment:")
print(assigned)
The chained call renames the column to new and replaces the value 1 with 100. The original frame still has its old column and the value 1, and assigning the result of rename gives the same renamed frame without the replacement. Older code often uses inplace=True to modify the object in place; that keyword is deprecated across Pandas 3.x, so assignment is the recommended approach.
$ python inplace_chaining.py chained result: new 0 100 1 2 2 3 original unchanged: old 0 1 1 2 2 3 after assignment: new 0 1 1 2 2 3
Source
Pandas DataFrame.rename Documentation, Pandas DataFrame.replace Documentation, and Pandas Series.map Documentation
In this article we have renamed column and index labels with rename, mapper/axis and direct assignment, replaced values with scalars, dictionaries and regular expressions, translated a Series with map, and seen why returning a copy and chaining is preferred over inplace. For changing the text inside string columns see Pandas string methods, and for applying functions column by column see Pandas apply, map and transform.
Author
List all Pandas tutorials.