To rename DataFrame column labels in pandas, use rename(columns=…) when you need to change one or more selected labels. This approach preserves every column you do not mention. To replace every label, assign a complete list to df.columns.
The right choice depends on whether you are making a targeted edit or defining the entire column layout. The examples below show how to change a DataFrame column name, rename several fields, and replace all labels safely.
Rename DataFrame column labels with rename(columns=…) for one or more selected fields
Pass a dictionary to rename(columns=…). Each dictionary key is an existing label, and its value is the new label. pandas returns a new DataFrame by default, so the original remains unchanged.
Example: import pandas as pd; df = pd.DataFrame({“first_name”: [“Mina”, “Omar”], “age”: [31, 28], “city”: [“Austin”, “Denver”]})
Rename one selected column and assign the returned DataFrame: renamed = df.rename(columns={“first_name”: “name”}). The renamed DataFrame has name, age, and city; the original df still has first_name.
To rename several columns at once, include each old-to-new pair in the dictionary: renamed = df.rename(columns={“first_name”: “name”, “age”: “years”, “city”: “location”}). Any column not included in the mapping keeps its existing label, which makes this method useful when you only need to change a few names in a wide DataFrame.
Dictionary keys must match the current labels exactly, including capitalization and spaces. For example, {“First Name”: “name”} does not match a column named first_name.
Set DataFrame column names by assigning a complete list
Use df.columns when you need to set DataFrame column names for every column at once. The list must contain one label for each existing column, in the same left-to-right order.
Example: With the three-column DataFrame above, replace all labels with df.columns = [“name”, “years”, “location”]. pandas assigns the first list item to the first column, the second to the second, and the third to the third.
This method requires a full replacement list. Unlike rename(columns=…), it does not preserve unspecified labels because you specify every label. It is useful when you want to standardize an entire schema, such as converting all headers to a known set of names.
You can also assign an existing list variable: new_names = [“name”, “years”, “location”]; df.columns = new_names. Keep the list order aligned with the data; assigning names does not reorder the columns or change their values.
Return a copy or modify the DataFrame with inplace
By default, rename() returns a modified copy. Use assignment when you want to keep the result in the same variable: df = df.rename(columns={“city”: “location”}). This is often clearer because it makes the updated object explicit.
To modify the existing DataFrame directly, pass inplace=True: df.rename(columns={“city”: “location”}, inplace=True). This operation returns None, so do not write df = df.rename(…, inplace=True); that would replace df with None.
Direct assignment with df.columns = […] also changes the existing DataFrame and does not return a separate renamed copy. Choose either assignment or inplace=True consistently in a workflow.
Avoid column-count mismatches and other renaming errors
- Check the list length. A DataFrame with three columns needs exactly three replacement labels. For example, df.columns = [“name”, “years”] raises a ValueError because the new list has two items instead of three.
- Check the current labels. A misspelled dictionary key normally produces no change. Inspect them with df.columns.tolist() before building a mapping.
- Use strict checking when needed. Add errors=”raise” to rename() if an absent mapping key should trigger an error: df.rename(columns={“nam”: “name”}, errors=”raise”).
- Watch the order of full-list assignments. pandas accepts the list by position, so an incorrectly ordered list can give columns misleading names without raising an error.