ZetCode

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.

rename_columns.py
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.

rename_index.py
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.

rename_mapper.py
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.

columns_assignment.py
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.

replace.py
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”.

replace_regex.py
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.

series_map.py
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.

inplace_chaining.py
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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Pandas tutorials.