Zmiana nazw kolumn w Pandas: kompletny przewodnik z przykładami

Jak zmieniać nazwy kolumn za pomocą .rename()?

Metoda .rename() to najbardziej elastyczny sposób na wykonanie operacji zmiany nazw kolumn w DataFrame pandas i najczęściej po nią sięgniesz. 

Przyjmuje słownik mapujący stare nazwy na nowe, pozostawia wszystkie niewymienione kolumny bez zmian i domyślnie zwraca nowy DataFrame zamiast modyfikować oryginał. Dzięki temu .rename() jest bezpieczne w łańcuchach metod i łatwe do ogarnięcia podczas debugowania.

Wzorzec słownika wygląda tak:

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

Jeśli dopiero zaczynasz ze słownikami, polecam nasz tutorial o metodach słowników w Pythonie jako odświeżenie.

Uwaga o starym parametrze copy

Krótko przed przykładami. Pandas 3.0 zdeprecjonował parametr copy i uczynił Copy-on-Write domyślnym zachowaniem. W praktyce oznacza to, że nie musisz się już martwić, czy .rename() robi kosztowną kopię danych. Pandas załatwia to leniwie pod spodem. Główny parametr, o którym warto myśleć, to inplace — omówimy go w trzeciej podsekcji.

Zmiana nazwy pojedynczej kolumny

Wyobraź sobie, że właśnie wczytałeś rekordy klientów wyeksportowane ze starego CRM. Nazwy kolumn są skrótami, które miały sens dla projektanta bazy w 2008 roku, ale nie dla ciebie. To najprostsza operacja zmiany nazw w pandas: jedna stara nazwa, jedna nowa, w słowniku:

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)

Teraz zmień cust_id_nbr na coś czytelniejszego:

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

Oryginalny DataFrame customers pozostał bez zmian. .rename() zwrócił nowy DataFrame, który przypisaliśmy do customers_renamed. Dwie nie wspomniane kolumny (first_nm, signup_dt) przyszły bez zmian.

Zmiana nazw wielu kolumn

Słownik skaluje się naturalnie. Aby obsłużyć zadanie zmiany nazw wielu kolumn w pandas, po prostu dodaj więcej par klucz–wartość do mapowania:

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

print(customers_clean)

Istnieje też alternatywna składnia używająca argumentów mapper i axis zamiast słowa kluczowego columns:

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

axis=1 mówi pandas, że celujesz w kolumny (w przeciwieństwie do axis=0 dla etykiet indeksu wierszy). Obie formy dają ten sam wynik. W większości kodu „na wolności” używa się columns={...}, bo czytelniej wygląda na pierwszy rzut oka, więc przy tym wzorcu pozostaniemy w reszcie tutorialu.

Przydatny szczegół: jeśli podasz klucz, który nie pasuje do żadnej istniejącej kolumny, .rename() domyślnie po prostu to zignoruje. To wygodne, gdy piszesz funkcję wielokrotnego użytku, która może obsługiwać DataFrame’y o nieco różnych schematach, ale może też ukryć literówki. Aby pandas zgłosił błąd dla nieznanych nazw kolumn, przekaż errors='raise'.

Użycie inplace vs. zwracanie nowego DataFrame

Domyślnie .rename() zwraca nowy DataFrame i zostawia oryginał w spokoju. Jeśli chcesz zmodyfikować istniejący DataFrame bezpośrednio, przekaż inplace=True:

# Zwraca nowy DataFrame (domyślnie)
customers_v2 = customers.rename(columns={"first_nm": "first_name"})

# Modyfikuje customers bezpośrednio, zwraca None
customers.rename(columns={"first_nm": "first_name"}, inplace=True)

print(customers)

Której opcji używać? W większości przypadków lepszy jest domyślny wariant zwracający nowy DataFrame. Łatwiej też wtedy debugować, bo w razie problemów masz oryginał do podglądu. I omijasz problemy z aliasowaniem, które w starszym kodzie wywoływały SettingWithCopyWarning.

Wydajność też nie jest już powodem, by preferować inplace. Dzięki Copy-on-Write, które jest domyślne w pandas 3.0+, wersja bez inplace korzysta z leniwego kopiowania. Dane są duplikowane dopiero przy modyfikacji. Stary argument, że inplace=True oszczędza pamięć, jest dziś dużo słabszy.

Jedno miejsce, gdzie inplace=True nadal bywa naturalne, to krótkie, eksploracyjne skrypty, w których czyścisz pojedynczy DataFrame krok po kroku i nie zależy ci na łańcuchowaniu. Do kodu produkcyjnego lub takiego, do którego wrócisz później, preferuj domyślną opcję.

Jak zmienić nazwy wszystkich kolumn naraz w Pandas?

Czasem nie chcesz mapować starych nazw na nowe. Chcesz po prostu podmienić wszystkie nazwy kolumn jednocześnie. To zdarza się częściej, niż byś się spodziewał — np. w CSV bez nagłówka, gdzie pandas nadał nazwy kolumn 0, 1, 2, w zbiorach danych, gdzie wiersz nagłówka jest w innym języku, albo w systemowych eksportach z nazwami w stylu Field1, Field2, Field3.

Są na to dwa popularne sposoby. Albo przypisanie bezpośrednio do df.columns, albo użycie .set_axis(). Dają ten sam efekt. Różnica to zwięzłość kontra możliwość łańcuchowania.

Przypisanie listy do df.columns

Najprostsze podejście to przypisanie nowej listy do atrybutu columns. Weź ten DataFrame zbudowany z list list bez informacji o nagłówkach — jak to bywa przy odczycie CSV bez nagłówka. Pandas używa wtedy liczbowych nazw kolumn:

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)

Nazwy kolumn 0, 1 i 2 są bezużyteczne w analizie. Podmień je, przypisując nową listę nazw do atrybutu columns:

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

Dwie rzeczy, które warto wiedzieć o tym podejściu. 

1. Długość listy musi się zgadzać co do sztuki. Jeśli podasz trzy nazwy dla DataFrame’u z czterema kolumnami, pandas zgłosi ValueError: Length mismatch (omówimy ten błąd później). 

2. To modyfikuje DataFrame w miejscu. Nie ma tu parametru inplace, bo samo przypisanie jest modyfikacją. Jeśli chcesz świeżą kopię, użyj najpierw .copy() albo sięgnij po .set_axis() poniżej.

Użycie .set_axis() do łańcuchowania metod

Metoda .set_axis() robi to samo, ale zwraca nowy DataFrame, więc możesz ją łańcuchować z innymi operacjami. Weź podobny DataFrame bez nagłówków, ale tym razem z nieco brudniejszymi danymi, jak dodatkowe miejsca po przecinku i brakujący odczyt:

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)

Argument axis=1 mówi pandas, że ustawiasz etykiety kolumn (użyj axis=0, aby ustawić indeks wierszy). Ponieważ .set_axis() zwraca nowy DataFrame, naturalnie pasuje do złożonych, łańcuchowych potoków transformacji, które piszesz w prawdziwym ETL lub analizie. To główny powód, by preferować je nad bezpośrednim przypisaniem w produkcji.

Jak zmieniać nazwy kolumn za pomocą funkcji w Pandas?

Zamiast mapować każdą starą nazwę na nową, możesz przekazać funkcję do .rename(), a pandas zastosuje ją do każdej nazwy kolumny. To właściwe narzędzie, gdy masz regułę zamiast listy. Na przykład „wszystko małymi literami” albo „zamień każdą spację na podkreślnik”.

Korzystanie z wbudowanych funkcji łańcuchów znaków

Najprostszym przypadkiem jest ujednolicanie wielkości liter. Przekaż str.lower, str.upper lub str.title bezpośrednio do argumentu 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())

Zwróć uwagę, że przekazujemy samą funkcję (str.lower), a nie jej wywołanie (str.lower()). Pandas stosuje ją do każdej nazwy z osobna. To zgrabny skrót do standaryzacji wielkości liter, ale nie obsługuje spacji ani znaków specjalnych. Do tego przyda się lambda lub własna funkcja.

Użycie lambdy i własnych funkcji

Do wszystkiego poza zmianą wielkości liter lambda daje szybki sposób, by wyrazić transformację inline. Jeśli nie używałeś wcześniej lambd, nasz przewodnik dla początkujących o funkcjach lambda w Pythonie to dobry start.

Częsty wzorzec to jednoczesne zamienienie na małe litery i zastąpienie spacji podkreślnikami. Użyjemy poprzedniego przykładu:

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

Gdy logika robi się bardziej rozbudowana, wynieś ją do nazwanej funkcji. Rozważ ten pomocnik, który konwertuje nazwy kolumn w camelCase lub PascalCase na 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())

Taka nazwana funkcja jest łatwiejsza do testowania, ponownego użycia w wielu notebookach i udokumentowania niż sprytny one-liner. Sięgaj po lambdy, gdy logika mieści się w jednej linii, a po własne funkcje — gdy nie.

Jak hurtowo czyścić brudne nazwy kolumn w Pandas?

Gdy dane przychodzą z arkuszy kalkulacyjnych, zewnętrznych API lub ręcznie edytowanych CSV, nazwy kolumn często mają problemy, których samo .rename() nie rozwiąże elegancko. Mam na myśli takie rzeczy jak:

• Końcowe białe znaki
• Mieszana wielkość liter
• Nawiasy
• Myślniki
• Znaki specjalne
• Niewidoczne znaki Unicode

W takich sytuacjach najczyściej jest operować bezpośrednio na df.columns używając akcesora .str, który udostępnia zwektoryzowane metody tekstowe (w tym regex) dla wszystkich nazw kolumn naraz. To także podstawa solidnego czyszczenia danych w Pythonie. Wyczyśczenie nazw kolumn sprawia, że każdy dalszy krok (filtrowanie, łączenie, wizualizacja) jest mniej podatny na błędy.

Usuwanie białych znaków i znaków specjalnych

Weź ten DataFrame, z nazwami jak z eksportu Excela dotykanego przez zbyt wiele osób:

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())

Początkowe i końcowe spacje to najczęstsze i najbardziej frustrujące problemy, bo są niewidoczne. Usuń je w jednej linii:

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

Dla znaków specjalnych .str.replace() akceptuje wyrażenie regularne. Poniższy wzorzec pozostawia litery, cyfry, podkreślenia i spacje, a resztę usuwa:

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

Myślnik, nawiasy i znak dolara zniknęły. Zauważ, że Total Amount ma teraz końcową spację (tam, gdzie wcześniej było ($)), a OrderDate całkiem straciło myślnik. Dlatego właśnie na końcu potoku czyszczenia znowu „stripujemy”.

Standaryzacja do snake_case

Dobrą praktyką jest konwersja wszystkich nazw kolumn do snake_case jeszcze przed rozpoczęciem analizy: małe litery, słowa oddzielone podkreśleniami, bez znaków specjalnych. Połącz metody .str, by osiągnąć to jednym wyrażeniem:

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()                                  # usuń początkowe/końcowe białe znaki
    .str.lower()                                  # wszystko małymi literami
    .str.replace(r"[^a-z0-9]+", "_", regex=True)  # zredukuj nie-alfanumeryki do podkreśleń
    .str.strip("_")                               # usuń początkowe/końcowe podkreślenia
)

print(raw_export.columns.tolist())

Cztery linie i twoje nazwy kolumn są przewidywalne, małymi literami i z podkreśleniami. Ten wzorzec warto zapisać jako funkcję narzędziową. Gdy ją masz, możesz stosować ją do każdego brudnego DataFrame’u, który wpadnie ci w ręce. 

Często będziesz też chciał połączyć zmianę nazw z usuwaniem kolumn. W tym celu tutorial o usuwaniu kolumn w pandas pokrywa kolejny krok.

Jak zmieniać nazwy kolumn podczas wczytywania danych w Pandas?

Jeśli już przed wczytaniem pliku wiesz, że chcesz inne nazwy kolumn, możesz zmienić je bezpośrednio w pd.read_csv(). Przekaż listę nazw do parametru names i ustaw header=0, by powiedzieć pandas, żeby pominął istniejący wiersz nagłówka i użył twoich nazw:

import pandas as pd
from io import StringIO

# Symulacja pliku CSV na potrzeby demonstracji
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"""

# Zmienia nazwy kolumn podczas wczytywania, pomijając oryginalny nagłówek
transactions = pd.read_csv(
    StringIO(csv_data),
    header=0,
    names=["transaction_id", "customer_id", "amount_usd", "transaction_date"]
)
print(transactions)

To przydatny skrót, gdy masz kontrolę nad schematem i nie chcesz osobnego kroku .rename() zaśmiecającego kod wczytywania. Jeśli plik w ogóle nie ma wiersza nagłówka, pomiń header=0 i po prostu użyj names=[...], aby nadać nazwy kolumn od zera. Po głębsze spojrzenie na opcje wczytywania polecam tutorial pandas read_csv().

Jedna uwaga: to podejście jest „albo wszystko, albo nic”. Parametr names podmienia każdą nazwę kolumny, więc długość listy musi dokładnie odpowiadać liczbie kolumn w pliku. Jeśli chcesz zmienić tylko kilka nazw, najpierw wczytaj plik i użyj .rename() później.

Aby przejść przez te wzorce krok po kroku wraz z innymi typowymi zadaniami czyszczenia, polecam nasz kurs Cleaning Data in Python.

Zmiana nazw kolumn w Polars vs. Pandas

Jeśli pracujesz zarówno w pandas, jak i w Polars, albo się tego spodziewasz, warto wiedzieć, jak każde z nich obsługuje zmianę nazw kolumn. API wysokiego poziomu jest podobne, ale szczegóły różnią się na sposoby, które potrafią zaskoczyć przy pierwszych podejściach. Polars to szybka, oparta na Ruście biblioteka DataFrame, coraz powszechniejsza w nowoczesnych stackach danych, a pamięć mięśniowa z pandas nie zawsze przekłada się 1:1.

Główna idea jest identyczna. Mapujesz stare nazwy na nowe za pomocą słownika. Różnice są w detalach. Polars jest z założenia niezmienny (brak inplace), łańcuchowanie metod to idiomatyczny styl, a zmiana nazwy kolumny podczas select korzysta z .alias(), a nie osobnego kroku rename.

Porównanie side-by-side

Ta sama zmiana nazwy w obu bibliotekach

Dla porównania — prosta zmiana nazw w każdej z dwóch bibliotek.

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)

Dwie drobne różnice. W Polars .rename() przyjmuje słownik bezpośrednio. Nie ma słowa kluczowego columns=, bo Polars wspiera tylko zmianę nazw kolumn (nie indeksu wierszy). I musisz przypisać wynik ponownie. W Polars nie ma inplace=True. Każda operacja zwraca nowy DataFrame.

Wynik Polars pokazuje też typy danych inline (i64, str) i kształt na górze — to jedna z drobnych rzeczy poprawiających komfort, które wiele osób docenia po przesiadce. 

Zmiana nazw kolumn podczas select

Podczas transformacji Polars używa .alias() wewnątrz .select() lub .with_columns():

# Polars
import polars as pl

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

# Wybierz i zmień nazwy w jednym wyrażeniu
renamed = orders_pl.select(
    pl.col("ord_id").alias("order_id"),
    pl.col("cust_nm").alias("customer_name")
)

print(renamed)

W pandas odpowiednikiem byłoby .rename() po wyborze kolumn. Żadne podejście nie jest „lepsze”. Odzwierciedlają filozofię projektową każdej biblioteki. 

Jeśli chcesz głębszego porównania, polecam tutorial o wydajności: pandas kontra polars. A jeśli chcesz dodać polars do swojego zestawu, polecam nasz kurs Introduction to Polars. 

Typowe błędy i jak je naprawić

Przy zmianie nazw kolumn w pandas powtarzają się dwa błędy. Oto jak wyglądają, dlaczego się zdarzają i jak je naprawić.

KeyError: nie znaleziono nazwy kolumny

Domyślnie .rename() po cichu ignoruje klucze, które nie pasują do żadnej istniejącej kolumny. Ale jeśli przekażesz errors='raise', by wyłapywać literówki, dostaniesz KeyError, gdy klucz nie istnieje:

import pandas as pd

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

# To zgłasza błąd
orders.rename(columns={"Order_ID": "order_id"}, errors="raise")

Najczęstszą przyczyną jest różnica w wielkości liter (Order_ID vs order_id) albo niewidzialna końcowa spacja ("order_id " vs "order_id"). Gdy trafisz na KeyError, sprawdź po kolei trzy rzeczy:

1. Dokładną pisownię i wielkość liter
2. Ukryte białe znaki
3. Czy kolumna nie została już wcześniej przemianowana

Aby zweryfikować rzeczywiste nazwy kolumn:

print(orders.columns.tolist())

# Alternatywnie użyj repr()
print([repr(c) for c in orders.columns])

Gdy zobaczysz dokładne łańcuchy, które trzyma pandas, literówka zwykle staje się oczywista. Popraw pisownię i uruchom ponownie:

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

Kiedy więc używać errors='raise' zamiast domyślnego errors='ignore'? 

• Domyślne zachowanie jest wyrozumiałe. Przydaje się w skryptach przetwarzających DataFrame’y o zmiennych schematach, gdzie brakująca kolumna nie powinna nic wywracać. 

• Przełącz na errors='raise', gdy chcesz, by literówki głośno wychodziły na jaw podczas developmentu, zwłaszcza w notebookach, gdzie ciche porażki potrafią kosztować godziny zagubionego debugowania później.

ValueError: length mismatch przy df.columns

Gdy przypisujesz listę do df.columns albo używasz .set_axis(), długość listy musi dokładnie odpowiadać liczbie kolumn. W przeciwnym razie pandas zgłosi ValueError:

import pandas as pd

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

# To zgłasza błąd
products.columns = ["product_sku", "product_name"]

DataFrame ma trzy kolumny, a podano tylko dwie nowe nazwy. Naprawa: sprawdź liczbę kolumn przed przypisaniem:

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

Jeśli pracujesz z DataFrame’ami, gdzie liczba kolumn może się zmieniać, bezpieczniej użyć .rename() ze słownikiem. Dotyka tylko nazwanych przez ciebie kolumn, więc brakująca lub dodatkowa kolumna nie wywróci kodu.

Na koniec

Zmiana nazw kolumn w pandas sprowadza się do dobrania metody do zakresu zadania. Niezależnie od podejścia największą praktyczną wygraną jest ustalenie jednej konwencji nazewniczej i stosowanie jej jako pierwszego kroku w każdej analizie. snake_case to standard w większości kodu Pythona. Czyste nazwy kolumn kosztują kilka sekund na starcie i oszczędzają ci niespodzianek KeyError przez resztę projektu.

Używaj .rename() ze słownikiem do celowanych zmian. Gdy każda kolumna ma dostać nową nazwę, przypisanie do df.columns lub .set_axis() jest szybsze niż budowanie słownika mapującego każdy stary–nowy. A jeśli zmiana podąża za regułą — jak usuwanie białych znaków, zamiana na małe litery, konwersja camelCase — to przekazanie funkcji lub użycie akcesora .str pozwala wyrazić regułę raz, zamiast wyliczać przypadki. Polars obsługuje to samo z podobnym API, ale jego niezmienny, „chain-first” styl popycha cię ku innym nawykom. 

Aby dalej rozwijać umiejętności pracy z DataFrame’ami, polecam kurs Data Manipulation with pandas jako kolejny krok. Jeśli wolisz ustrukturyzowaną ścieżkę nauki, ścieżka kariery Data Analyst in Python obejmuje manipulację DataFrame’ami wraz z resztą narzędzi analityka.