Written and maintained by CASRAI Editorial Board
Last updated
To rename columns in a pandas DataFrame, call df.rename(columns={'old_name': 'new_name'}) and assign the result back to a variable. Labels you do not list stay unchanged. This guide follows the current pandas documentation (version 3.1.0, checked 2026-10-29), including two changes older tutorials miss: inplace=True is deprecated, and a misspelled key is silently ignored unless you ask for an error.
What renaming columns is used for in research
Column names are the variable names of a dataset. Raw exports from survey platforms, instruments and spreadsheets often arrive with names like Q3 (Age) or Temp C that are awkward to type and easy to mistype. Renaming them once, in code, to the names used in your codebook means every later step refers to the same variables, and anyone re-running the script gets the same result. That makes the rename step part of a computationally reproducible workflow rather than a manual edit in a spreadsheet. It is usually one of the first steps of data cleaning and data wrangling, and it supports the naming conventions in tidy data rules for research data.
Install or access
pandas is distributed through PyPI, conda-forge and as source on GitHub. The pandas installation page recommends working inside a virtual environment.
- pip:
pip install pandas - conda:
conda install -c conda-forge pandas - New conda environment:
conda create -c conda-forge -n name_of_my_env python pandas, thenconda activate name_of_my_env
The installation page defers supported Python versions to the pandas Python support policy, so check that page before installing into an older environment.
Step-by-step: rename columns in a pandas DataFrame
The examples use the small DataFrame from the pandas documentation:
import pandas as pd
df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})1. Rename selected columns with a dictionary
Pass a dictionary of old name to new name to the columns keyword of DataFrame.rename:
df = df.rename(columns={"A": "a", "B": "c"})The columns are now a and c. The documentation states that labels not contained in the dictionary are left as they are, and that extra labels in the dictionary do not raise an error. The docs also say they highly recommend keyword arguments, so write columns= rather than relying on position.
2. Rename every column with a function
The mapper can be a function applied to each label. Combined with axis="columns" it standardises every name at once:
df = df.rename(str.lower, axis="columns")For the example frame this yields columns a and b. Passing a mapper with axis=1 or axis="columns" is equivalent to columns=mapper. The documentation notes that function or dictionary values must be unique (one-to-one).
3. Replace all labels at once with set_axis
When you want to supply the complete list of new names in column order, use DataFrame.set_axis:
df = df.set_axis(["I", "II"], axis="columns")The columns become I and II. You must provide one label per column, in the existing order. set_axis has no inplace parameter and returns a new DataFrame.
4. Add a prefix or suffix to every column
DataFrame.add_prefix prepends text to each column label of a DataFrame, and add_suffix appends it:
df = df.add_prefix("col_")For the example frame the columns become col_A and col_B. This is handy for marking the source of columns before combining datasets. The axis parameter of add_prefix was added in pandas 2.0.0.
5. Rename one level of a MultiIndex
For columns with a MultiIndex, rename accepts a level argument so that only that level is relabelled.
Output and how to read it
rename returns a DataFrame with the new labels, or None if inplace=True is used. Print df.columns or df.head() after the call and compare against your codebook. Since pandas 3.0 the copy keyword is deprecated and ignored: rename always returns a new object, with copying handled lazily under Copy-on-Write, so the original DataFrame is not modified unless you assign the result back to the same name.
Troubleshooting
My rename did nothing and raised no error
The default is errors="ignore", so a key that does not match any column (a typo, a trailing space, different capitalisation) is skipped silently. Ask for an error instead:
df.rename(columns={"A": "a", "B": "b", "C": "c"}, errors="raise")With the example frame this raises KeyError: ['C'] not found in axis because there is no column C. In a research pipeline, errors="raise" turns a quiet naming mistake into a failure you notice before analysis. After renaming, an explicit check that the expected names are present is a cheap safeguard.
The original DataFrame did not change
That is expected. Write df = df.rename(...). Do not rely on inplace=True: the documentation marks it as deprecated since pandas 3.1.0 and scheduled for removal in pandas 4.0, and it returns None, so df = df.rename(..., inplace=True) would overwrite your DataFrame with None.
Two columns end up with the same name
The documentation says function and dictionary values must be unique (1-to-1). Give each column its own new label rather than mapping two old names to one new name.
Which method to use: built-in options compared
All four methods are part of pandas itself, which is free and open source. Each row follows the pandas documentation pages listed under Sources.
| Method | Use it when | Behaviour documented by pandas |
|---|---|---|
rename(columns={...}) |
Changing some columns | Unlisted labels are left as-is; extra keys do not raise unless errors="raise" |
rename(function, axis="columns") |
Applying one rule to every name, such as str.lower |
Function applied to each label; values must be unique |
set_axis(labels, axis="columns") |
Replacing every name with a full list | One label per column, in order; no inplace; returns a new DataFrame |
add_prefix / add_suffix |
Marking all columns with the same text | Prefixes (or suffixes) each column label of a DataFrame |
Frequently asked questions
How do I rename a single column in pandas?
Use df = df.rename(columns={"old": "new"}) with one entry in the dictionary. Other columns are unchanged.
How do I rename all columns in a pandas DataFrame?
Use set_axis with a full list of names in column order, or rename with a function such as str.lower and axis="columns".
Is inplace=True still recommended?
No. The pandas documentation lists inplace on rename as deprecated since version 3.1.0, to be removed in pandas 4.0. Assign the returned DataFrame instead.
How do I make rename fail on a wrong column name?
Pass errors="raise". A dictionary containing labels that are not in the columns then raises a KeyError.
Where do I go next?
Once variables are named consistently, you can move on to analysis and plotting, for example scatter plots in Python or ANOVA in Python with statsmodels.
Sources
All links below were checked on 2026-10-29.
- pandas documentation, DataFrame.rename (checked 2026-10-29)
- pandas documentation, DataFrame.set_axis (checked 2026-10-29)
- pandas documentation, DataFrame.add_prefix (checked 2026-10-29)
- pandas documentation, Installation (checked 2026-10-29)
