Rinominare colonne in pandas: guida completa con esempi

Come rinomino le colonne con .rename()?

Il metodo .rename() è il modo più flessibile per eseguire un'operazione di rinomina colonne in un DataFrame pandas, ed è quello a cui ricorrerai più spesso. 

Accetta un dizionario che mappa i vecchi nomi ai nuovi, lascia intatte tutte le colonne che non menzioni e per impostazione predefinita restituisce un nuovo DataFrame invece di modificare l'originale. Questo rende .rename() sicuro da usare all'interno di catene di metodi e facile da ragionare in fase di debug.

Il pattern del dizionario è così:

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

Se sei alle prime armi con i dizionari, ti consiglio di dare un'occhiata al nostro tutorial sui metodi dei dizionari in Python per un ripasso.

Nota sul vecchio parametro copy

Una breve nota prima degli esempi. Pandas 3.0 ha deprecato il parametro copy e ha reso Copy-on-Write il comportamento predefinito. In pratica, significa che non devi più preoccuparti se .rename() stia creando una copia costosa dei tuoi dati. Pandas lo gestisce in modo lazy sotto il cofano. Il parametro principale su cui riflettere è inplace, che tratteremo nella terza sottosezione.

Rinominare una singola colonna

Immagina di aver appena caricato record di clienti esportati da un CRM legacy. I nomi delle colonne sono abbreviati in un modo che aveva senso per chi ha progettato il database nel 2008, ma non per te. Questa è l'operazione di rinomina più semplice in pandas: un vecchio nome, un nuovo nome, in un dizionario:

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)

Ora rinomina cust_id_nbr in qualcosa di più leggibile:

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

Il DataFrame customers originale è invariato. .rename() ha restituito un nuovo DataFrame, che abbiamo assegnato a customers_renamed. Le due colonne che non abbiamo menzionato (first_nm, signup_dt) sono rimaste invariate.

Rinominare più colonne

Il dizionario è naturalmente scalabile. Per gestire un'attività di rinomina di più colonne in pandas, aggiungi semplicemente più coppie chiave-valore alla mappatura:

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

print(customers_clean)

Esiste anche una sintassi alternativa che usa gli argomenti mapper e axis invece della keyword columns:

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

Il axis=1 dice a pandas che stai mirando alle colonne (in contrapposizione a axis=0 per le etichette dell'indice delle righe). Entrambe le forme producono lo stesso risultato. Gran parte del codice in circolazione usa columns={...} perché è più leggibile a colpo d'occhio, quindi manterremo questo pattern per il resto del tutorial.

Un dettaglio utile è che se passi una chiave che non corrisponde a nessuna colonna esistente, .rename() la ignora in silenzio per impostazione predefinita. È comodo quando scrivi una funzione riutilizzabile che potrebbe gestire DataFrame con schemi leggermente diversi, ma può anche nascondere refusi. Per far sì che pandas generi un errore su nomi di colonna sconosciuti, passa errors='raise'.

Usare inplace vs. restituire un nuovo DataFrame

Per impostazione predefinita, .rename() restituisce un nuovo DataFrame e lascia l'originale intatto. Se vuoi modificare direttamente il DataFrame esistente, passa inplace=True:

# Restituisce un nuovo DataFrame (default)
customers_v2 = customers.rename(columns={"first_nm": "first_name"})

# Modifica direttamente customers, restituisce None
customers.rename(columns={"first_nm": "first_name"}, inplace=True)

print(customers)

Quindi, quale dovresti usare? Nella maggior parte dei casi, la scelta migliore è il default, cioè restituire un nuovo DataFrame. È anche più facile da debuggare, poiché hai ancora il DataFrame originale da ispezionare quando qualcosa va storto. E evita i problemi di aliasing che producono un SettingWithCopyWarning nel codice più vecchio.

Le prestazioni non sono più un motivo valido per preferire inplace. Con il Copy-on-Write, ora predefinito in pandas 3.0+, la versione non-inplace usa la copia lazy. I dati non vengono effettivamente duplicati finché qualcosa non viene modificato. Il vecchio argomento secondo cui inplace=True risparmia memoria è molto più debole di un tempo.

L'unico contesto in cui inplace=True risulta ancora naturale è in script brevi ed esplorativi, dove pulisci un singolo DataFrame passo dopo passo e non ti interessa concatenare i metodi. Per codice di produzione o qualsiasi cosa rivedrai in seguito, preferisci il default.

Come rinomino tutte le colonne in una volta in pandas?

A volte non vuoi mappare vecchi nomi su nuovi. Vuoi semplicemente sostituire tutti i nomi delle colonne in una volta. Questo capita più spesso del previsto: CSV senza intestazione in cui pandas assegna 0, 1, 2 come nomi di colonna, dataset in cui la riga di intestazione è in un'altra lingua, o esportazioni generate da sistemi con nomi come Field1, Field2, Field3.

Ci sono due modi comuni per farlo. Assegnando direttamente a df.columns, oppure usando .set_axis(). Producono lo stesso risultato. Il compromesso è tra brevità e possibilità di concatenare metodi.

Assegnare una lista a df.columns

L'approccio più diretto è assegnare una nuova lista all'attributo columns. Prendi questo DataFrame, costruito da una lista di liste senza informazioni di intestazione, come il tipo di cosa che ottieni leggendo un CSV senza header. Pandas ripiega su nomi di colonna interi:

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)

Quei nomi di colonna 0, 1 e 2 sono inutili per l'analisi. Sostituiscili assegnando una nuova lista di nomi all'attributo columns:

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

Due cose da sapere su questo approccio. 

1. La lunghezza della lista deve corrispondere esattamente. Se passi tre nomi per un DataFrame a quattro colonne, pandas solleva ValueError: Length mismatch (tratteremo questo errore in dettaglio più avanti). 

2. Modifica il DataFrame in place. Qui non esiste il parametro inplace perché l'assegnazione è la modifica. Se vuoi una copia nuova, usa prima .copy() o ricorri a .set_axis() qui sotto.

Usare .set_axis() per concatenare metodi

Il metodo .set_axis() fa la stessa cosa, ma restituisce un nuovo DataFrame così puoi concatenarlo con altre operazioni. Prendi un DataFrame simile senza intestazione, ma questa volta con dati più disordinati, come decimali extra e una lettura mancante:

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)

L'argomento axis=1 dice a pandas che stai impostando le etichette delle colonne (usa axis=0 per impostare invece l'indice delle righe). Poiché .set_axis() restituisce un nuovo DataFrame, si inserisce naturalmente nel tipo di pipeline di trasformazioni concatenate che scriverai in un vero codice ETL o di analisi. È il motivo principale per preferirlo all'assegnazione diretta in produzione.

Come rinomino le colonne usando funzioni in pandas?

Invece di mappare ogni vecchio nome a uno nuovo, puoi passare una funzione a .rename(), e pandas la applicherà a ogni nome di colonna. È lo strumento giusto quando hai una regola piuttosto che un elenco. Ad esempio, "mettere tutto in minuscolo" o "sostituire ogni spazio con un underscore".

Usare funzioni stringa integrate

Il caso più semplice è la standardizzazione del caso. Passa direttamente str.lower, str.upper o str.title all'argomento 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())

Nota che stiamo passando la funzione in sé (str.lower), non chiamandola (str.lower()). Pandas la applica a ogni nome di colonna uno alla volta. È una scorciatoia pulita per standardizzare il case, ma non gestisce spazi o caratteri speciali. Per quelli, ti servirà una lambda o una funzione personalizzata.

Usare lambda e funzioni personalizzate

Per tutto ciò che va oltre i cambi di maiuscole/minuscole, una lambda ti dà un modo rapido per esprimere la trasformazione inline. Se non hai mai usato le lambda, la nostra guida introduttiva alle funzioni lambda in Python è un buon punto di partenza.

Un pattern comune è mettere in minuscolo e sostituire gli spazi con underscore in un solo passaggio. Usiamo l'esempio precedente:

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

Quando la logica si fa più articolata, estraila in una funzione nominata. Considera questo helper che converte nomi di colonna in camelCase o PascalCase in 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())

Una funzione nominata come questa è più facile da testare, riutilizzare tra notebook e documentare rispetto a una one-liner ingegnosa. Usa le lambda quando la logica sta su una riga, e funzioni personalizzate quando non ci sta.

Come pulisco in blocco nomi di colonna disordinati in pandas?

Quando i dati arrivano da fogli di calcolo, API di terze parti o CSV modificati a mano, i nomi delle colonne spesso hanno problemi che .rename() da solo non può risolvere con eleganza. Parlo di problemi come:

• Spazi bianchi finali
• Casing misto
• Parentesi
• Trattini
• Caratteri speciali
• Caratteri Unicode invisibili

Per queste situazioni, l'approccio più pulito è operare direttamente su df.columns usando l'accessor .str, che espone metodi stringa vettorializzati (inclusa la regex) su tutti i nomi di colonna in una volta. Questa è anche la base di una solida pulizia dei dati in Python. Pulire i nomi delle colonne rende ogni passaggio a valle (filtri, join, grafici) meno soggetto a errori.

Rimuovere spazi bianchi e caratteri speciali

Prendi questo DataFrame, con i tipici nomi che otterresti da un'esportazione Excel toccata da troppe mani:

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

Gli spazi iniziali e finali sono i problemi più comuni e più frustranti, perché sono invisibili. Rimuovili in una riga:

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

Per i caratteri speciali, .str.replace() accetta un pattern regex. Il pattern qui sotto mantiene lettere, numeri, underscore e spazi, e rimuove tutto il resto:

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

Il trattino, le parentesi e il simbolo del dollaro sono spariti. Nota che Total Amount ora ha uno spazio finale (dove prima c'era ($)), e OrderDate ha perso del tutto il trattino. È proprio per questo che facciamo di nuovo lo strip alla fine di una pipeline di pulizia.

Standardizzare in snake_case

Una buona pratica comune è convertire tutti i nomi di colonna in snake_case prima di iniziare qualsiasi analisi: tutto minuscolo, parole separate da underscore, niente caratteri speciali. Collega i metodi .str per arrivarci in un'unica espressione:

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()                                  # rimuovi spazi iniziali/finali
    .str.lower()                                  # tutto in minuscolo
    .str.replace(r"[^a-z0-9]+", "_", regex=True)  # comprimi i non alfanumerici in underscore
    .str.strip("_")                               # rimuovi underscore iniziali/finali
)

print(raw_export.columns.tolist())

Quattro righe, e i tuoi nomi di colonna sono prevedibili, minuscoli e separati da underscore. Questo pattern merita di essere salvato come funzione di utilità. Una volta che ce l'hai, puoi lanciarlo contro ogni DataFrame disordinato che ti arriva.

Spesso vorrai combinare la rinomina con la rimozione di colonne. Per quello, il tutorial su come eliminare colonne in pandas copre il passo successivo.

Come rinomino le colonne durante il caricamento dei dati in pandas?

Se sai già che vuoi nomi di colonna diversi prima ancora di caricare il file, puoi fare la rinomina direttamente dentro pd.read_csv(). Passa una lista di nomi al parametro names e imposta header=0 per dire a pandas di saltare la riga di intestazione esistente e usare invece i tuoi nomi:

import pandas as pd
from io import StringIO

# Simulazione di un file CSV per dimostrazione
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"""

# Rinomina le colonne in fase di caricamento, saltando l'header originale
transactions = pd.read_csv(
    StringIO(csv_data),
    header=0,
    names=["transaction_id", "customer_id", "amount_usd", "transaction_date"]
)
print(transactions)

Questa è una scorciatoia utile quando controlli lo schema e non vuoi un passaggio .rename() separato a ingombrare il codice di caricamento. Se il file non ha alcuna riga di intestazione, ometti header=0 e usa semplicemente names=[...] per assegnare i nomi delle colonne da zero. Per uno sguardo più approfondito alle opzioni di caricamento dei dataset, ti consiglierei il tutorial pandas read_csv().

Una avvertenza: questo è un approccio tutto-o-niente. Il parametro names sostituisce ogni nome di colonna, quindi la lunghezza della lista deve corrispondere esattamente al numero di colonne nel file. Se vuoi rinominare solo alcune colonne, carica prima il file e usa .rename() dopo.

Per una guida passo passo a questi pattern insieme ad altri comuni compiti di pulizia, ti consiglio di seguire il nostro corso Cleaning Data in Python.

Rinominare colonne in Polars vs. Pandas

Se lavori sia con pandas che con Polars, o pensi di farlo, vale la pena sapere come ciascuno gestisce la rinomina delle colonne. L'API ad alto livello è simile, ma i dettagli divergono in modi che ti possono sorprendere le prime volte. Polars è una libreria DataFrame veloce, basata su Rust, sempre più comune negli stack dati moderni, e la memoria muscolare che costruisci in pandas non sempre si trasferisce in modo lineare.

L'idea principale è identica. Mappi vecchi nomi a nuovi con un dizionario. Le differenze stanno nei dettagli. Polars è immutabile per design (niente inplace), il chaining di metodi è lo stile idiomatico, e la rinomina a livello di colonna durante un select usa .alias() invece di un passaggio di rinomina separato.

Confronto affiancato

La stessa rinomina in entrambe le librerie

Per confronto, ecco una semplice rinomina in ciascuna delle due librerie.

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)

Due piccole differenze da notare. Il .rename() di Polars accetta direttamente il dizionario. Non c'è la keyword columns= perché Polars supporta solo la rinomina delle colonne (non dell'indice delle righe). E devi riassegnare il risultato. In Polars non esiste inplace=True. Ogni operazione restituisce un nuovo DataFrame.

L'output di Polars mostra anche i dtype inline (i64, str) e la shape in alto, una delle piccole comodità che spesso piacciono a chi passa a Polars. 

Rinominare le colonne durante un select

Per rinominare durante una trasformazione, Polars usa .alias() dentro .select() o .with_columns():

# Polars
import polars as pl

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

# Seleziona e rinomina in un'unica espressione
renamed = orders_pl.select(
    pl.col("ord_id").alias("order_id"),
    pl.col("cust_nm").alias("customer_name")
)

print(renamed)

In pandas, l'equivalente sarebbe un .rename() dopo una selezione di colonne. Nessun approccio è migliore in assoluto. Riflettono la filosofia di design di ciascuna libreria. 

Se vuoi un confronto più approfondito tra le due, ti consiglio il tutorial pandas versus polars performance. E se vuoi aggiungere polars al tuo kit, ti consiglio il nostro Introduction to Polars course. 

Errori comuni e come risolverli

Due errori si presentano ripetutamente quando si rinominano colonne in pandas. Ecco come si manifestano, perché accadono e come risolverli.

KeyError: nome colonna non trovato

Per impostazione predefinita, .rename() ignora in silenzio le chiavi che non corrispondono a nessuna colonna esistente. Ma se passi errors='raise' per intercettare i refusi, otterrai un KeyError quando una chiave non esiste:

import pandas as pd

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

# Questo genera un errore
orders.rename(columns={"Order_ID": "order_id"}, errors="raise")

La causa più comune è uno scivolone di maiuscole/minuscole (Order_ID contro order_id) o uno spazio finale invisibile ("order_id " contro "order_id"). Quando incontri un KeyError, controlla tre cose in ordine:

1. Ortografia e maiuscole esatte
2. Spazi bianchi nascosti
3. Se la colonna è già stata rinominata prima

Per verificare i nomi di colonna effettivi:

print(orders.columns.tolist())

# Usa repr() come alternativa
print([repr(c) for c in orders.columns])

Una volta che vedi le stringhe esatte che pandas sta mantenendo, il refuso di solito salta all'occhio. Quindi correggi l'ortografia e riesegui:

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

Resta da capire quando usare errors='raise' rispetto al default errors='ignore'. 

• Il default è tollerante. È utile in script che elaborano DataFrame con schemi variabili, dove una colonna mancante non dovrebbe mandare tutto in crash. 

• Passa a errors='raise' quando vuoi che i refusi emergano chiaramente durante lo sviluppo, specialmente nei notebook dove i fallimenti silenziosi causano ore di debug confuso a valle.

ValueError: lunghezza non corrispondente con df.columns

Quando assegni una lista a df.columns o usi .set_axis(), la lunghezza della lista deve corrispondere esattamente al numero di colonne. Se non lo fa, pandas solleva un ValueError:

import pandas as pd

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

# Questo genera un errore
products.columns = ["product_sku", "product_name"]

Il DataFrame ha tre colonne, ma sono stati forniti solo due nuovi nomi. La soluzione è verificare il numero di colonne prima dell'assegnazione:

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

Se lavori con DataFrame in cui il numero di colonne può variare, è più sicuro usare .rename() con un dizionario. Tocca solo le colonne che nomini, quindi una colonna mancante o extra non manderà in crash il tuo codice.

Considerazioni finali

Rinominare le colonne in pandas si riduce a scegliere il metodo che corrisponde all'ampiezza del tuo compito. Qualunque approccio tu scelga, la vittoria pratica più grande è stabilire una convenzione di denominazione unica e applicarla come primo passo di ogni analisi. snake_case è quello che usa la maggior parte del codice Python. Nomi di colonna puliti richiedono pochi secondi all'inizio e ti risparmiano sorprese da KeyError per il resto del progetto.

Usa .rename() con un dizionario per rinomine mirate. Quando ogni colonna ha bisogno di un nuovo nome, assegnare a df.columns o usare .set_axis() è più veloce che costruire un dizionario di ogni mappatura vecchio-nuovo. E se la rinomina segue una regola come rimuovere spazi bianchi, mettere tutto in minuscolo, convertire camelCase, allora passare una funzione o usare l'accessor .str ti permette di esprimere la regola una volta invece di elencare i casi. Polars gestisce lo stesso lavoro con un'API simile, ma il suo stile immutabile e chain-first ti porta verso abitudini diverse. 

Per continuare a costruire le tue abilità con i DataFrame, ti consiglio come prossimo passo il corso Data Manipulation with pandas. Se vuoi un percorso di apprendimento strutturato, la carriera Data Analyst in Python copre la manipolazione dei DataFrame insieme al resto degli strumenti da analista.