columns is technically just the DataFrame's column-axis Index, the same Index type used for rows, which is why column names support the same fast, label-based lookup behavior as a row index. Reading df.columns gives you the current column names as an Index, convert to a plain list with .tolist() if needed, and assigning a new list of the same length directly to df.columns replaces every column name at once — a common way to rename columns in bulk when you have a full replacement list, as opposed to df.rename(), which is better suited for renaming just a few specific columns by their old name.

1Understanding df.columns

💡

Assigning a whole new list to df.columns replaces every column name at once and requires the new list to have exactly the same length as the current number of columns — use df.rename(columns={...}) instead when you only want to rename a few specific columns by name.

editor.html

import pandas as pd

df = pd.DataFrame({"first_name": ["Alice"], "last_name": ["Smith"]})
print(df.columns.tolist())

localhost:3000

2Practical Example

Here is a real-world application of df.columns showing how it is used in production Pandas code.

editor.html

import pandas as pd

df = pd.DataFrame({"a": [1], "b": [2]})
df.columns = ["first", "second"]
print(df.columns.tolist())

localhost:3000

3Best Practices

Follow these guidelines when working with df.columns:

1. Use df.rename(columns={...}) for renaming just a few specific columns by their existing name, rather than reassigning the entire columns list

2. Reassign df.columns directly only when replacing every column name at once with a full, matching-length list

3. Convert df.columns to a plain list with .tolist() when you need to pass it somewhere that expects an ordinary Python list rather than an Index

⚠️

Tip: Assigning a whole new list to df.columns replaces every column name at once and requires the new list to have exactly the same length as the current number of columns — use df.rename(columns={...}) instead when you only want to rename a few specific columns by name.

editor.html

import pandas as pd

df = pd.DataFrame({"first_name": ["Alice"], "last_name": ["Smith"]})
print(df.columns.tolist())

localhost:3000

Examples

Example 01Basic Usage

import pandas as pd

df = pd.DataFrame({"first_name": ["Alice"], "last_name": ["Smith"]})
print(df.columns.tolist())

Example 02Advanced Example

import pandas as pd

df = pd.DataFrame({"a": [1], "b": [2]})
df.columns = ["first", "second"]
print(df.columns.tolist())

Best Practices

Use df.rename(columns={...}) for renaming just a few specific columns by their existing name, rather than reassigning the entire columns list
Reassign df.columns directly only when replacing every column name at once with a full, matching-length list
Convert df.columns to a plain list with .tolist() when you need to pass it somewhere that expects an ordinary Python list rather than an Index

Interview Question

What's the difference between renaming columns by assigning a new list to df.columns, versus using df.rename(columns={...})?▼

Hint: Think about whether you need to replace every column name, or just a few specific ones.

Assigning directly to df.columns replaces every single column name at once, positionally, and requires the new list to have exactly the same number of elements as the DataFrame currently has columns — it's an all-or-nothing bulk replacement. df.rename(columns={'old_name': 'new_name'}) instead targets specific columns by their current name, leaving every other column's name completely untouched, which is more convenient and less error-prone when you only need to rename one or a few columns rather than relabeling the entire DataFrame.

Exercises

MediumPractice using df.columns in a real scenario.

View Solution

import pandas as pd

df = pd.DataFrame({"first_name": ["Alice"], "last_name": ["Smith"]})
print(df.columns.tolist())

Frequently Asked Questions

What's the difference between renaming columns by assigning a new list to df.columns, versus using df.rename(columns={...})?▼

Related Functions

df-renamepd-indexdf-dtypes