Skip to main content

How to Rename Columns in a pandas DataFrame

· 4 min read
Jagdish Kumawat
Founder @ Dewiride

Column names that come from a file or another program are often longer or clumsier than you want, such as price_usd where price would do. pandas renames columns with one call, rename, and a dictionary from old names to new ones. This guide renames two columns, shows that the original table is untouched, and makes a misspelled name raise an error instead of passing silently, with real output from pandas 3.1.1.

Syntax​

Syntax
new_frame = frame.rename(columns={"<old name>": "<new name>"})
PartWhat it means
frameThe DataFrame whose columns you rename
columns={...}A dictionary: each key is a current column name, each value its new name. List only the columns you want to change
new_framerename returns a new DataFrame; frame keeps its old names
errors="raise"Optional: raise a KeyError when a name in the dictionary isn't a column. By default such names are skipped

Step 1: Rename Two Columns​

The example is a table of two fruits and their prices in US dollars. Create rename_columns.py:

The rename_columns.py script in a macOS-style code window: it builds a DataFrame with fruit_name and price_usd columns for apple and banana, renames the columns to fruit and price with rename, prints the renamed table, and prints the original table's columns.

rename_columns.py
import pandas as pd

fruit = pd.DataFrame({"fruit_name": ["apple", "banana"], "price_usd": [1.20, 0.50]})

renamed = fruit.rename(columns={"fruit_name": "fruit", "price_usd": "price"})
print(renamed)
print("Original columns:", list(fruit.columns))
Terminal
uv run python rename_columns.py
Output
fruit price
0 apple 1.2
1 banana 0.5
Original columns: ['fruit_name', 'price_usd']

A terminal running uv run python rename_columns.py: a table with the columns fruit and price for apple 1.2 and banana 0.5, then Original columns: ['fruit_name', 'price_usd'].

The new table has the short names; the original, fruit, still has the old ones. To keep the new names, assign the result, here to renamed, or back to the same variable: fruit = fruit.rename(...).

Step 2: Make a Misspelled Name an Error​

By default, a name in the dictionary that isn't a column is skipped without a word. Create rename_strict.py, which asks for a colour column that the table doesn't have:

rename_strict.py
import pandas as pd

fruit = pd.DataFrame({"fruit_name": ["apple", "banana"], "price_usd": [1.20, 0.50]})

print(list(fruit.rename(columns={"colour": "color"}).columns))
fruit.rename(columns={"colour": "color"}, errors="raise")
Terminal
uv run python rename_strict.py
Output (first and last lines)
['fruit_name', 'price_usd']
KeyError: "['colour'] not found in axis"

The first call changed nothing and said nothing. With errors="raise", the same call stops with a KeyError that names the missing column, so a typo can't slip through.

Common Mistakes​

MistakeWhat happensDo this instead
Calling fruit.rename(...) without keeping the resultfruit keeps its old namesfruit = fruit.rename(...)
Misspelling an old nameNothing is renamed, and no errorPass errors="raise"
rename({"fruit_name": "fruit"}) without columns=pandas renames row labels insteadWrite columns={...}

Troubleshooting​

SymptomLikely causeFix
KeyError: "['colour'] not found in axis"errors="raise" and a name that isn't a columnCheck the names with list(frame.columns)
The new name doesn't appearThe result wasn't assignedAssign it to a variable
Two columns end up with the same nameTwo old names were mapped to one new nameGive each a distinct new name

FAQ​

How do I rename every column at once?​

List every column in the dictionary, or assign a new list of names: fruit.columns = ["fruit", "price"], which must have one name per column.

Can I rename with a function?​

Yes: columns= also takes a function that receives each name, such as str.upper.

Does rename change the data?​

No. Only the column labels change; the values stay the same.

Conclusion​

frame.rename(columns={"fruit_name": "fruit", "price_usd": "price"}) returned a new DataFrame with the short names and left the original alone. Assign the result to keep it, and add errors="raise" so a misspelled name raises a KeyError instead of being skipped.

Additional Resources​