Переименование столбцов в pandas: полное руководство с примерами

Как переименовать столбцы с помощью .rename()?

Метод .rename() — самый гибкий способ выполнить операцию переименования столбцов в pandas DataFrame и тот, к которому вы будете прибегать чаще всего. 

Он принимает словарь, который сопоставляет старые имена с новыми, оставляет неупомянутые столбцы без изменений и по умолчанию возвращает новый DataFrame, не модифицируя исходный. Это делает .rename() безопасным для использования в цепочках методов и удобным для отладки.

Шаблон со словарём выглядит так:

sales_data.rename(columns={"old_name": "new_name"})

Если вы подзабыли работу со словарями, рекомендую освежить память с помощью нашего руководства по методам словарей в Python.

Замечание о старом параметре copy

Коротко перед примерами. В pandas 3.0 параметр copy объявлен устаревшим, а Copy-on-Write стал поведением по умолчанию. На практике это означает, что больше не нужно беспокоиться о том, делает ли .rename() дорогую копию данных. Pandas делает это лениво «под капотом». Основной параметр, о котором стоит думать, — это inplace; мы рассмотрим его в третьем подразделе.

Переименование одного столбца

Представьте, что вы только что загрузили клиентские записи из устаревшей CRM. Имена столбцов сокращены так, как это имело смысл для автора базы в 2008 году, но не для вас. Это самый простой случай переименования: одно старое имя, одно новое, в словаре:

import pandas as pd

customers = pd.DataFrame({
    "cust_id_nbr": [4521, 4522, 4523, 4524],
    "first_nm": ["Abe", "Rick", "Pat", "Kim"],
    "signup_dt": ["2008-03-12", "2008-03-15", "2008-03-18", "2008-03-21"]
})

print(customers)

Теперь переименуем cust_id_nbr во что-то более читаемое:

customers_renamed = customers.rename(columns={"cust_id_nbr": "customer_id"})
print(customers_renamed)

Исходный DataFrame customers не изменился. .rename() вернул новый DataFrame, который мы присвоили переменной customers_renamed. Два столбца, которые мы не упоминали (first_nm, signup_dt), пришли без изменений.

Переименование нескольких столбцов

Словарь естественно масштабируется. Чтобы выполнить задачу по переименованию сразу нескольких столбцов, просто добавьте больше пар ключ–значение в отображение:

customers_clean = customers.rename(columns={
    "cust_id_nbr": "customer_id",
    "first_nm": "first_name",
    "signup_dt": "signup_date"
})

print(customers_clean)

Есть и альтернативный синтаксис с аргументами mapper и axis вместо ключевого слова columns:

customers.rename(mapper={"cust_id_nbr": "customer_id"}, axis=1)

Аргумент axis=1 указывает pandas, что вы нацелены на столбцы (в отличие от axis=0 для меток индекса строк). Оба варианта дают одинаковый результат. В «диком» коде чаще используют columns={...}, потому что это легче считывается с первого взгляда, поэтому дальше мы будем придерживаться именно этого паттерна.

Полезная деталь: если вы передадите ключ, который не совпадает ни с одним существующим столбцом, .rename() по умолчанию просто проигнорирует его. Это удобно, когда вы пишете переиспользуемую функцию для DataFrame'ов со слегка разными схемами, но может скрывать опечатки. Чтобы заставить pandas выбрасывать ошибку при неизвестных именах столбцов, укажите errors='raise'.

Использование inplace против возврата нового DataFrame

По умолчанию .rename() возвращает новый DataFrame и не трогает исходный. Если хотите модифицировать существующий DataFrame напрямую, передайте inplace=True:

# Возвращает новый DataFrame (по умолчанию)
customers_v2 = customers.rename(columns={"first_nm": "first_name"})

# Модифицирует customers напрямую, возвращает None
customers.rename(columns={"first_nm": "first_name"}, inplace=True)

print(customers)

Что же выбрать? В большинстве случаев лучше оставить поведение по умолчанию — возвращать новый DataFrame. Так проще отлаживать, потому что у вас остаётся исходный DataFrame для проверки, если что-то пойдёт не так. И это помогает обойти проблемы алиасинга, которые порождали SettingWithCopyWarning в старом коде.

Производительность больше не повод предпочитать inplace. С Copy-on-Write, который теперь по умолчанию в pandas 3.0+, не-inplace версия использует ленивое копирование. Фактическое дублирование данных происходит только при модификации. Старый аргумент о том, что inplace=True экономит память, уже не так убедителен.

Единственное место, где inplace=True всё ещё уместен, — короткие исследовательские скрипты, в которых вы пошагово чистите один DataFrame и вам не важны цепочки. Для продакшн-кода или того, к чему вы вернётесь позже, лучше предпочесть режим по умолчанию.

Как переименовать все столбцы сразу в pandas?

Иногда вам не нужно сопоставлять старые имена с новыми. Вы хотите разом заменить все имена столбцов. Это случается чаще, чем кажется: CSV без заголовка, где pandas присвоил имена 0, 1, 2, наборы данных, где строка заголовка на другом языке, или системные выгрузки с именами вроде Field1, Field2, Field3.

Есть два распространённых способа: присвоить напрямую df.columns или использовать .set_axis(). Результат одинаковый. Компромисс — между краткостью и удобством цепочек.

Присвоение списка df.columns

Самый прямой подход — присвоить новый список атрибуту columns. Возьмём этот DataFrame, собранный из списка списков без информации о заголовках, как при чтении CSV без заголовка. Pandas подставляет целочисленные имена столбцов:

import pandas as pd

sensor_readings = pd.DataFrame([
    [1.2, 22.5, 1013],
    [1.5, 22.7, 1012],
    [1.3, 22.6, 1013]
])

print(sensor_readings)

Имена столбцов 0, 1 и 2 бесполезны для анализа. Замените их, присвоив новый список имён атрибуту columns:

sensor_readings.columns = ["wind_speed", "temperature_c", "pressure_hpa"]
print(sensor_readings)

Два важных момента. 

1. Длина списка должна совпадать в точности. Если передать три имени для DataFrame с четырьмя столбцами, pandas поднимет ValueError: Length mismatch (эту ошибку разберём ниже). 

2. Это модификация на месте. Параметра inplace здесь нет, поскольку само присвоение и есть изменение. Если нужен новый объект, сначала используйте .copy() или выберите .set_axis() ниже.

Использование .set_axis() для цепочек методов

Метод .set_axis() делает то же самое, но возвращает новый DataFrame, чтобы вы могли включить его в цепочку операций. Возьмём похожий DataFrame без заголовков, но уже с «грязными» данными, например с лишними знаками после запятой и пропущенным значением:

raw_sensor = pd.DataFrame([
    [1.234, 22.567, 1013],
    [1.512, 22.789, 1012],
    [None,  22.601, 1013],
    [1.345, 22.612, 1013]
])

sensor_clean = (
    raw_sensor
    .set_axis(["wind_speed_mps", "temp_celsius", "pressure_hpa"], axis=1)
    .round(1)
    .dropna()
)

print(sensor_clean)

Аргумент axis=1 указывает pandas, что вы задаёте метки столбцов (используйте axis=0, чтобы задать индекс строк). Поскольку .set_axis() возвращает новый DataFrame, он органично вписывается в цепочки трансформаций, которые вы пишете в реальном ETL или аналитическом коде. Это основная причина предпочесть его прямому присвоению в продакшне.

Как переименовывать столбцы функциями в pandas?

Вместо сопоставления каждого старого имени с новым вы можете передать функцию в .rename(), и pandas применит её к каждому имени столбца. Это верный инструмент, когда у вас есть правило, а не список. Например: «всё в нижний регистр» или «заменить каждый пробел на подчёркивание».

Использование встроенных строковых функций

Самый простой случай — стандартизация регистра. Передайте str.lower, str.upper или str.title напрямую в аргумент columns:

import pandas as pd

orders = pd.DataFrame({
    "Order ID": [1001, 1002, 1003],
    "Customer Name": ["Abe", "Rick", "Pat"],
    "Total Amount": [49.99, 120.00, 75.50]
})

orders_lower = orders.rename(columns=str.lower)
print(orders_lower.columns.tolist())

Обратите внимание, что мы передаём саму функцию (str.lower), а не вызываем её (str.lower()). Pandas применяет её к каждому имени по одному. Это аккуратный шорткат для стандартизации регистра, но он не обрабатывает пробелы и спецсимволы. Для этого пригодится lambda или своя функция.

Lambda и пользовательские функции

Для всего, что выходит за рамки изменения регистра, lambda позволяет кратко выразить трансформацию inline. Если вы не работали с lambda раньше, наш вводный гид по функциям lambda в Python — хорошая отправная точка.

Распространённый паттерн — привести к нижнему регистру и заменить пробелы на подчёркивания за один шаг. Используем предыдущий пример:

orders_snake = orders.rename(columns=lambda col: col.lower().replace(" ", "_"))
print(orders_snake.columns.tolist())

Когда логика усложняется, вынесите её в именованную функцию. Рассмотрим помощник, который конвертирует имена в camelCase или PascalCase в snake_case:

import re

def to_snake_case(name: str) -> str:
    """Convert camelCase or PascalCase to snake_case."""
    s1 = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
    s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
    return s2.lower()

api_response = pd.DataFrame({
    "userId": [1, 2, 3],
    "firstName": ["Abe", "Rick", "Pat"],
    "accountCreatedAt": ["2024-01-01", "2024-01-02", "2024-01-03"]
})

api_clean = api_response.rename(columns=to_snake_case)
print(api_clean.columns.tolist())

Такую именованную функцию проще тестировать, переиспользовать между ноутбуками и документировать, чем изящную однострочную. Используйте lambda, когда логика умещается в одну строку, и пользовательские функции — когда нет.

Как массово очищать «грязные» имена столбцов в pandas?

Когда данные приходят из таблиц, сторонних API или вручную правленных CSV, имена столбцов часто имеют проблемы, которые .rename() не решает элегантно. Речь о таких вещах, как:

• пробелы в конце
• смешанный регистр
• скобки
• дефисы
• спецсимволы
• невидимые символы Unicode

В таких ситуациях самый чистый подход — работать напрямую с df.columns через аксессор .str, который открывает векторизованные строковые методы (включая regex) сразу для всех имён столбцов. Это также основа надёжной очистки данных в Python. Очищенные имена столбцов делают все последующие шаги (фильтрацию, объединение, визуализацию) менее подверженными ошибкам.

Удаление пробелов и спецсимволов

Возьмём этот DataFrame — типичные имена из Excel-экспорта, к которому приложили руку слишком многие:

import pandas as pd

raw_export = pd.DataFrame({
    "  Order ID ": [1001, 1002, 1003],
    "Customer Name (Full)": ["Abe", "Rick", "Pat"],
    "Total Amount ($)": [49.99, 120.00, 75.50],
    "Order-Date": ["2024-03-12", "2024-03-15", "2024-03-18"]
})

print(raw_export.columns.tolist())

Лидирующие и хвостовые пробелы — самые частые и самые раздражающие проблемы, потому что их не видно. Уберите их одной строкой:

raw_export.columns = raw_export.columns.str.strip()
print(raw_export.columns.tolist())

Для спецсимволов .str.replace() принимает шаблон regex. Шаблон ниже сохраняет буквы, цифры, подчёркивания и пробелы, а всё остальное удаляет:

raw_export.columns = raw_export.columns.str.replace(r"[^a-zA-Z0-9_ ]", "", regex=True)
print(raw_export.columns.tolist())

Дефис, скобки и знак доллара исчезли. Обратите внимание, что у Total Amount теперь пробел на конце (на месте бывших ($)), а OrderDate полностью потерял дефис. Именно поэтому мы снова делаем strip в конце конвейера очистки.

Стандартизация до snake_case

Распространённая практика — привести все имена столбцов к snake_case до начала анализа: нижний регистр, слова разделены подчёркиваниями, без спецсимволов. Сцепите методы .str, чтобы получить это одним выражением:

raw_export = pd.DataFrame({
    "  Order ID ": [1001, 1002, 1003],
    "Customer Name (Full)": ["Abe", "Rick", "Pat"],
    "Total Amount ($)": [49.99, 120.00, 75.50],
    "Order-Date": ["2024-03-12", "2024-03-15", "2024-03-18"]
})

raw_export.columns = (
    raw_export.columns
    .str.strip()                                  # убрать пробелы по краям
    .str.lower()                                  # всё в нижний регистр
    .str.replace(r"[^a-z0-9]+", "_", regex=True)  # схлопнуть неалфанумерические в подчёркивания
    .str.strip("_")                               # удалить подчёркивания в начале/конце
)

print(raw_export.columns.tolist())

Четыре строки — и имена столбцов стали предсказуемыми, строчными и разделёнными подчёркиваниями. Этот паттерн стоит сохранить как утилиту. Однажды написав, вы сможете применять его к любому «грязному» DataFrame.

Часто захочется сочетать переименование с удалением столбцов. Для этого следующий шаг разобран в руководстве по удалению столбцов в pandas.

Как переименовывать столбцы при загрузке данных в pandas?

Если вы заранее знаете, что хотите другие имена столбцов ещё до загрузки файла, можно переименовать их прямо внутри pd.read_csv(). Передайте список имён в параметр names и задайте header=0, чтобы указать pandas пропустить существующую строку заголовка и использовать ваши имена вместо неё:

import pandas as pd
from io import StringIO

# Имитируем CSV-файл для демонстрации
csv_data = """txnId,custId,amt,date
1001,C01,49.99,2024-01-15
1002,C02,125.00,2024-01-16
1003,C01,79.50,2024-01-17"""

# Переименовываем столбцы на этапе загрузки, пропуская исходный заголовок
transactions = pd.read_csv(
    StringIO(csv_data),
    header=0,
    names=["transaction_id", "customer_id", "amount_usd", "transaction_date"]
)
print(transactions)

Это полезный шорткат, когда вы контролируете схему и не хотите захламлять код загрузки отдельным шагом .rename(). Если в файле вовсе нет строки заголовка, опустите header=0 и просто используйте names=[...], чтобы назначить имена столбцов с нуля. За более глубоким обзором параметров загрузки рекомендую руководство pandas read_csv().

Оговорка: это подход «всё или ничего». Параметр names заменяет все имена столбцов, поэтому длина списка должна в точности совпадать с числом столбцов в файле. Если нужно переименовать только несколько столбцов, сначала загрузите файл, затем используйте .rename().

Для пошаговой проработки этих паттернов вместе с другими типичными задачами очистки рекомендую пройти курс Cleaning Data in Python.

Переименование столбцов в Polars и в pandas

Если вы работаете и с pandas, и с Polars, или планируете, полезно знать, как каждая библиотека обрабатывает переименование. Высокоуровневый API похож, но детали различаются и поначалу сбивают с толку. Polars — быстрая библиотека DataFrame на Rust, всё чаще встречающаяся в современных стеках данных, и мышечная память из pandas переносится не всегда гладко.

Главная идея та же: вы сопоставляете старые имена с новыми через словарь. Отличия — в деталях. Polars по дизайну неизменяем (нет inplace), идиоматичный стиль — метод-цепочки, а переименование на уровне столбца в select делает .alias(), а не отдельный шаг rename.

Сравнение бок о бок

Одинаковое переименование в обеих библиотеках

Для сравнения — простое переименование в каждой из двух библиотек.

Pandas:

# Pandas
import pandas as pd

orders_pd = pd.DataFrame({
    "ord_id": [1001, 1002, 1003],
    "cust_nm": ["Abe", "Rick", "Pat"]
})

orders_pd = orders_pd.rename(columns={"ord_id": "order_id", "cust_nm": "customer_name"})
print(orders_pd)

Polars:

# Polars
import polars as pl

orders_pl = pl.DataFrame({
    "ord_id": [1001, 1002, 1003],
    "cust_nm": ["Abe", "Rick", "Pat"]
})

orders_pl = orders_pl.rename({"ord_id": "order_id", "cust_nm": "customer_name"})
print(orders_pl)

Два небольших отличия. В Polars .rename() принимает словарь напрямую. Нет ключевого слова columns=, потому что Polars поддерживает только переименование столбцов (не индекса строк). И нужно переназначать результат — inplace=True в Polars не существует. Каждая операция возвращает новый DataFrame.

Вывод Polars также показывает типы данных inline (i64, str) и форму сверху — мелочь, которая многим нравится после перехода.

Переименование столбцов в ходе select

Для переименования в ходе трансформации Polars использует .alias() внутри .select() или .with_columns():

# Polars
import polars as pl

orders_pl = pl.DataFrame({
    "ord_id": [1001, 1002, 1003],
    "cust_nm": ["Abe", "Rick", "Pat"]
})

# Выбрать и переименовать в одном выражении
renamed = orders_pl.select(
    pl.col("ord_id").alias("order_id"),
    pl.col("cust_nm").alias("customer_name")
)

print(renamed)

В pandas эквивалент — .rename() после выбора столбцов. Ни один из подходов не лучше — они отражают философию дизайна каждой библиотеки. 

Если хотите более глубокое сравнение, рекомендую руководство по производительности pandas и polars. А если хотите добавить polars в свой инструментарий, рекомендую наш курс Introduction to Polars.

Частые ошибки и как их исправлять

При переименовании столбцов в pandas регулярно встречаются две ошибки. Вот как они выглядят, почему возникают и как их исправить.

KeyError: column name not found

По умолчанию .rename() молча игнорирует ключи, не совпадающие ни с одним столбцом. Но если вы передадите errors='raise', чтобы ловить опечатки, получите KeyError, когда ключ не существует:

import pandas as pd

orders = pd.DataFrame({
    "order_id": [1001, 1002, 1003],
    "customer_name": ["Abe", "Rick", "Pat"]
})

# Это вызовет ошибку
orders.rename(columns={"Order_ID": "order_id"}, errors="raise")

Чаще всего причина — чувствительность к регистру (Order_ID против order_id) или невидимый пробел в конце ("order_id " против "order_id"). Столкнувшись с KeyError, проверьте по порядку три вещи:

1. точное написание и регистр
2. скрытые пробелы
3. не был ли столбец уже переименован ранее

Чтобы проверить фактические имена столбцов:

print(orders.columns.tolist())

# Альтернатива — repr()
print([repr(c) for c in orders.columns])

Увидев точные строки, которые хранит pandas, вы обычно сразу замечаете опечатку. Затем исправьте написание и перезапустите:

orders = orders.rename(columns={"order_id": "Order_ID"}, errors="raise")
print(orders.columns.tolist())

Теперь вопрос — когда использовать errors='raise' против значения по умолчанию errors='ignore'. 

• Значение по умолчанию снисходительно. Оно удобно в скриптах, которые обрабатывают DataFrame'ы с меняющимися схемами, где отсутствие столбца не должно всё ломать. 

• Переключайтесь на errors='raise', когда хотите, чтобы опечатки громко проявлялись в разработке, особенно в ноутбуках, где тихие сбои порождают часы путаницы далее по конвейеру.

ValueError: length mismatch при работе с df.columns

Когда вы присваиваете список в df.columns или используете .set_axis(), длина списка должна точно совпадать с количеством столбцов. Иначе pandas поднимет ValueError:

import pandas as pd

products = pd.DataFrame({
    "sku": ["A100", "A101", "A102"],
    "name": ["Widget", "Gadget", "Gizmo"],
    "price": [9.99, 14.99, 19.99]
})

# Это вызовет ошибку
products.columns = ["product_sku", "product_name"]

В DataFrame три столбца, а новых имён передано только два. Решение — проверить количество столбцов перед присвоением:

print(len(products.columns))
products.columns = ["product_sku", "product_name", "product_price"]
print(products.columns.tolist())

Если вы работаете с DataFrame'ами, где число столбцов может меняться, безопаснее использовать .rename() со словарём. Он затрагивает только названные вами столбцы, поэтому отсутствующий или лишний столбец не уронит ваш код.

Итоги

Переименование столбцов в pandas сводится к выбору метода под масштаб задачи. Какой бы подход вы ни выбрали, самый практичный выигрыш — определить единый стиль именования и применять его первым шагом в каждом анализе. snake_case — то, что использует большинство Python-проектов. Чистые имена столбцов занимают секунды в начале и спасают от сюрпризов KeyError до конца проекта.

Используйте .rename() со словарём для точечных переименований. Когда все столбцы нуждаются в новых именах, присваивание df.columns или .set_axis() быстрее, чем собирать словарь всех соответствий «старое → новое». А если переименование следует правилу — убрать пробелы, привести к нижнему регистру, конвертировать camelCase — то передача функции или использование аксессора .str позволяют выразить правило один раз вместо перечисления случаев. Polars решает те же задачи похожим API, но его неизменяемость и ориентация на цепочки приучают к иным привычкам. 

Чтобы продолжить развивать навыки работы с DataFrameами, рекомендую курс Data Manipulation with pandas в качестве следующего шага. Если ищете структурированный учебный путь, карьерный трек Data Analyst in Python охватывает работу с DataFrame наряду с остальным инструментарием аналитика.