Renombrar columnas en pandas: guía completa con ejemplos

¿Cómo renombro columnas con .rename()?

El método .rename() es la forma más flexible de renombrar columnas en un DataFrame de pandas, y al que recurrirás la mayoría de las veces. 

Recibe un diccionario que mapea nombres antiguos a nuevos, deja intactas las columnas que no menciones y, por defecto, devuelve un DataFrame nuevo en lugar de modificar el original. Esto hace que .rename() sea seguro dentro de cadenas de métodos y fácil de razonar al depurar.

El patrón del diccionario tiene esta forma:

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

Si los diccionarios no los tienes frescos, te recomiendo repasar nuestro tutorial de métodos de diccionario en Python.

Nota sobre el antiguo parámetro copy

Una nota rápida antes de los ejemplos. Pandas 3.0 desaprobó el parámetro copy e hizo que Copy-on-Write fuera el comportamiento por defecto. En la práctica, significa que ya no tienes que preocuparte por si .rename() hace una copia costosa de tus datos. Pandas lo gestiona de forma perezosa internamente. El principal parámetro que queda por considerar es inplace, que veremos en la tercera subsección.

Renombrar una sola columna

Imagina que acabas de cargar registros de clientes exportados de un CRM heredado. Los nombres de columna están abreviados de una forma que tenía sentido para quien diseñó la base de datos en 2008, pero no para ti. Este es el caso más simple: un nombre antiguo y uno nuevo en un diccionario:

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)

Ahora, cambia cust_id_nbr por algo más legible:

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

El DataFrame original customers no cambia. .rename() devuelve un DataFrame nuevo que asignamos a customers_renamed. Las dos columnas que no mencionamos (first_nm, signup_dt) pasan intactas.

Renombrar varias columnas

El diccionario escala de forma natural. Para renombrar varias columnas, añade más pares clave-valor al mapeo:

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

print(customers_clean)

También hay una sintaxis alternativa que usa los argumentos mapper y axis en lugar de la palabra clave columns:

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

El axis=1 le dice a pandas que apuntas a columnas (frente a axis=0 para etiquetas del índice de filas). Ambas formas producen el mismo resultado. En la práctica, la mayoría del código usa columns={...} porque se lee más claro de un vistazo, así que seguiremos ese patrón en el resto del tutorial.

Un detalle útil: si pasas una clave que no coincide con ninguna columna existente, .rename() la ignora en silencio por defecto. Es cómodo cuando escribes una función reutilizable que puede recibir DataFrames con esquemas ligeramente distintos, pero también puede ocultar erratas. Para que pandas lance un error con nombres desconocidos, pasa errors='raise'.

Usar inplace frente a devolver un nuevo DataFrame

Por defecto, .rename() devuelve un DataFrame nuevo y deja el original intacto. Si quieres modificar el DataFrame existente directamente, pasa inplace=True:

# Devuelve un DataFrame nuevo (por defecto)
customers_v2 = customers.rename(columns={"first_nm": "first_name"})

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

print(customers)

Entonces, ¿cuál usar? En la mayoría de los casos, la opción por defecto, devolver un DataFrame nuevo, es la mejor. También es más fácil de depurar, porque sigues teniendo el DataFrame original para inspeccionarlo si algo falla. Y evita los problemas de aliasing que producían un SettingWithCopyWarning en código antiguo.

El rendimiento ya no es un motivo para preferir inplace. Con Copy-on-Write, ahora por defecto en pandas 3.0+, la versión no in-place usa copias perezosas. No duplica los datos hasta que algo cambia. El viejo argumento de que inplace=True ahorra memoria es hoy mucho más débil.

El único sitio donde inplace=True sigue resultando natural es en scripts exploratorios cortos donde limpias un único DataFrame paso a paso y no te importa encadenar métodos. Para código de producción o algo que vayas a retomar, mejor quédate con el comportamiento por defecto.

¿Cómo renombro todas las columnas a la vez en pandas?

A veces no quieres mapear nombres antiguos a nuevos. Quieres reemplazar todos los nombres de columna de golpe. Esto pasa más a menudo de lo que piensas: CSV sin cabecera donde pandas asigna 0, 1, 2 como nombres, datasets donde la cabecera está en otro idioma o exportaciones de sistemas con nombres como Field1, Field2, Field3.

Hay dos formas típicas de hacerlo: asignando directamente a df.columns o usando .set_axis(). Producen el mismo resultado. El equilibrio está entre brevedad y posibilidad de encadenar.

Asignar una lista a df.columns

El enfoque más directo es asignar una lista nueva al atributo columns. Toma este DataFrame, construido a partir de una lista de listas sin información de cabecera, como lo que obtienes al leer un CSV sin encabezados. Pandas recurre a nombres de columna enteros:

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)

Esos nombres de columna 0, 1 y 2 no sirven para analizar. Reemplázalos asignando una lista nueva al atributo columns:

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

Dos cosas a tener en cuenta. 

1. La longitud de la lista debe coincidir exactamente. Si pasas tres nombres para un DataFrame de cuatro columnas, pandas lanzará ValueError: Length mismatch (veremos este error más adelante). 

2. Modifica el DataFrame in place. Aquí no hay parámetro inplace porque la asignación ya es la modificación. Si quieres una copia nueva, usa .copy() antes o recurre a .set_axis() más abajo.

Usar .set_axis() para encadenar métodos

El método .set_axis() hace lo mismo, pero devuelve un DataFrame nuevo para que puedas encadenarlo con otras operaciones. Toma un DataFrame sin cabecera similar, pero esta vez con datos más sucios como más decimales y una lectura ausente:

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)

El argumento axis=1 indica a pandas que estás estableciendo las etiquetas de columnas (usa axis=0 para el índice de filas). Como .set_axis() devuelve un DataFrame nuevo, encaja de forma natural en los pipelines de transformaciones encadenadas que escribirás en ETL o análisis reales. Esa es la principal razón para preferirlo frente a la asignación directa en producción.

¿Cómo renombro columnas usando funciones en pandas?

En lugar de mapear cada nombre antiguo a uno nuevo, puedes pasar una función a .rename() y pandas la aplicará a todos los nombres de columna. Es la herramienta adecuada cuando tienes una regla y no una lista. Por ejemplo, "poner todo en minúsculas" o "reemplazar cada espacio por un guion bajo".

Usar funciones de cadena integradas

El caso más simple es estandarizar el uso de mayúsculas y minúsculas. Pasa str.lower, str.upper o str.title directamente al argumento 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())

Fíjate en que pasamos la función en sí (str.lower), no la llamamos (str.lower()). Pandas la aplica a cada nombre de columna. Es un atajo limpio para estandarizar el caso, pero no resuelve espacios ni caracteres especiales. Para eso, usa una lambda o una función personalizada.

Usar lambdas y funciones personalizadas

Para algo más que cambios de mayúsculas/minúsculas, una lambda te permite expresar la transformación en una sola línea. Si no has usado lambdas, nuestra guía para principiantes de funciones lambda en Python es un buen punto de partida.

Un patrón común es poner en minúsculas y reemplazar espacios por guiones bajos en un paso. Usamos el ejemplo anterior:

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

Cuando la lógica se complica, sáquela a una función con nombre. Considera este helper que convierte nombres en camelCase o PascalCase a 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 función con nombre como esta es más fácil de testear, reutilizar entre notebooks y documentar que una línea ingeniosa. Recurre a lambdas cuando la lógica cabe en una línea, y a funciones personalizadas cuando no.

¿Cómo limpio nombres de columna desordenados en bloque en pandas?

Cuando los datos llegan desde hojas de cálculo, APIs de terceros o CSV editados a mano, los nombres de columna suelen tener problemas que .rename() no resuelve con elegancia. Me refiero a cosas como:

• Espacios en blanco al final
• Mayúsculas y minúsculas mezcladas
• Paréntesis
• Guiones
• Caracteres especiales
• Caracteres Unicode invisibles

Para estas situaciones, el enfoque más limpio es operar directamente sobre df.columns usando el accesor .str, que expone métodos vectorizados de cadenas (incluido regex) sobre todos los nombres de columna a la vez. Esta es también la base de una buena limpieza de datos en Python. Limpiar los nombres de columna hace que cada paso posterior (filtrar, unir, graficar) sea menos propenso a errores.

Eliminar espacios y caracteres especiales

Toma este DataFrame, con nombres del estilo que obtendrías de una exportación de Excel por la que han pasado demasiadas manos:

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

Los espacios al principio y al final son el problema más común y más frustrante, porque son invisibles. Límpialos en una línea:

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

Para caracteres especiales, .str.replace() acepta un patrón regex. El patrón siguiente mantiene letras, números, guiones bajos y espacios, y elimina todo lo demás:

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

El guion, los paréntesis y el símbolo de dólar han desaparecido. Observa que Total Amount ahora tiene un espacio al final (donde antes estaba ($)), y OrderDate ha perdido el guion por completo. Por eso conviene volver a hacer strip al final de una canalización de limpieza.

Estandarizar a snake_case

Una buena práctica común es convertir todos los nombres de columna a snake_case antes de empezar cualquier análisis: minúsculas, palabras separadas por guiones bajos, sin caracteres especiales. Encadena los métodos de .str para llegar ahí en una sola expresión:

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()                                  # elimina espacios al inicio/final
    .str.lower()                                  # todo en minúsculas
    .str.replace(r"[^a-z0-9]+", "_", regex=True)  # colapsa no alfanuméricos en guiones bajos
    .str.strip("_")                               # elimina guiones bajos al inicio/final
)

print(raw_export.columns.tolist())

Cuatro líneas y tus nombres de columna son predecibles, en minúsculas y separados por guiones bajos. Este patrón merece la pena guardarlo como función de utilidad. Cuando lo tengas, podrás aplicarlo a cada DataFrame desordenado que te llegue. 

A menudo querrás combinar renombrado con eliminación de columnas. Para eso, el tutorial de cómo eliminar columnas en pandas te cubre el siguiente paso.

¿Cómo renombro columnas al cargar datos en pandas?

Si ya sabes que quieres nombres de columna distintos antes incluso de cargar el archivo, puedes renombrar directamente dentro de pd.read_csv(). Pasa una lista de nombres al parámetro names y establece header=0 para decirle a pandas que omita la cabecera existente y use los tuyos:

import pandas as pd
from io import StringIO

# Simulamos un archivo CSV para la demostración
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"""

# Renombra columnas al cargar, omitiendo la cabecera original
transactions = pd.read_csv(
    StringIO(csv_data),
    header=0,
    names=["transaction_id", "customer_id", "amount_usd", "transaction_date"]
)
print(transactions)

Es un atajo útil cuando controlas el esquema y no quieres que un .rename() aparte te ensucie el código de carga. Si el archivo no tiene cabecera, omite header=0 y usa solo names=[...] para asignar nombres desde cero. Para profundizar en las opciones de carga, te recomiendo el tutorial pandas read_csv().

Un aviso: es un enfoque de todo o nada. El parámetro names reemplaza todos los nombres de columna, así que la longitud de la lista debe coincidir exactamente con el número de columnas del archivo. Si solo quieres renombrar unas pocas, carga primero y usa .rename() después.

Para un recorrido guiado por estos patrones junto con otras tareas comunes de limpieza, te recomiendo el curso Cleaning Data in Python.

Renombrar columnas en Polars vs. pandas

Si trabajas con pandas y Polars, o esperas hacerlo, merece la pena saber cómo maneja cada uno el renombrado de columnas. La API a alto nivel es similar, pero los detalles divergen de formas que pueden pillarte al principio. Polars es una librería rápida de DataFrames en Rust cada vez más común en stacks modernos, y la memoria muscular de pandas no siempre se traslada tal cual.

La idea principal es idéntica: mapeas nombres antiguos a nuevos con un diccionario. Las diferencias están en los detalles. Polars es inmutable por diseño (no hay inplace), el encadenado de métodos es el estilo idiomático y el renombrado a nivel de columna durante un select usa .alias() en lugar de un paso de renombrado aparte.

Comparativa lado a lado

El mismo renombrado en ambas librerías

Para comparar, aquí tienes un renombrado simple en cada una.

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)

Dos pequeñas diferencias a notar. .rename() de Polars recibe el diccionario directamente. No hay palabra clave columns= porque Polars solo soporta renombrar columnas (no hay índice de filas). Y tienes que reasignar el resultado. No existe inplace=True en Polars. Toda operación devuelve un DataFrame nuevo.

La salida de Polars también muestra los dtypes en línea (i64, str) y la forma arriba, uno de esos pequeños detalles de calidad de vida que suelen gustar cuando te pasas.

Renombrar columnas durante un select

Para renombrar durante una transformación, Polars usa .alias() dentro de .select() o .with_columns():

# Polars
import polars as pl

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

# Selecciona y renombra en una sola expresión
renamed = orders_pl.select(
    pl.col("ord_id").alias("order_id"),
    pl.col("cust_nm").alias("customer_name")
)

print(renamed)

En pandas, el equivalente sería un .rename() después de seleccionar columnas. Ningún enfoque es mejor: reflejan la filosofía de cada librería. 

Si quieres una comparación más profunda entre ambas, te recomiendo el tutorial pandas versus polars performance. Y si quieres sumar Polars a tu kit, te sugiero nuestro curso Introduction to Polars. 

Errores comunes y cómo solucionarlos

Hay dos errores que aparecen una y otra vez al renombrar columnas en pandas. Así se ven, por qué ocurren y cómo arreglarlos.

KeyError: column name not found

Por defecto, .rename() ignora en silencio las claves que no coinciden con ninguna columna. Pero si pasas errors='raise' para atrapar erratas, obtendrás un KeyError cuando una clave no exista:

import pandas as pd

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

# Esto lanza un error
orders.rename(columns={"Order_ID": "order_id"}, errors="raise")

La causa más común es una diferencia de mayúsculas/minúsculas (Order_ID frente a order_id) o un espacio invisible al final ("order_id " frente a "order_id"). Cuando te topes con un KeyError, comprueba tres cosas en orden:

1. Ortografía exacta y uso de mayúsculas/minúsculas
2. Espacios ocultos
3. Si la columna ya se renombró antes

Para verificar los nombres reales de columna:

print(orders.columns.tolist())

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

Una vez veas las cadenas exactas que guarda pandas, el error suele saltar a la vista. Corrige la grafía y vuelve a ejecutar:

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

La cuestión es cuándo usar errors='raise' frente al valor por defecto errors='ignore'. 

• El valor por defecto es permisivo. Viene bien en scripts que procesan DataFrames con esquemas variables, donde una columna ausente no debería romper nada. 

• Cambia a errors='raise' cuando quieras que las erratas salgan a la luz durante el desarrollo, sobre todo en notebooks donde los fallos silenciosos acaban en horas de depuración cuesta arriba.

ValueError: length mismatch con df.columns

Cuando asignas una lista a df.columns o usas .set_axis(), la longitud debe coincidir exactamente con el número de columnas. Si no, pandas lanza un ValueError:

import pandas as pd

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

# Esto lanza un error
products.columns = ["product_sku", "product_name"]

El DataFrame tiene tres columnas, pero solo se proporcionaron dos nombres. La solución es comprobar el recuento antes de asignar:

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

Si trabajas con DataFrames donde el número de columnas puede variar, es más seguro usar .rename() con un diccionario. Solo toca las columnas que indiques, así que una columna extra o ausente no romperá tu código.

Conclusiones

Renombrar columnas en pandas consiste en elegir el método que encaja con el alcance de tu tarea. El mayor beneficio práctico es fijar una convención de nombres y aplicarla como primer paso en cada análisis. snake_case es lo más habitual en Python. Unos nombres limpios te cuesta segundos al inicio y te ahorran sorpresas de KeyError durante el resto del proyecto.

Usa .rename() con un diccionario para cambios puntuales. Cuando todas las columnas necesiten nombre nuevo, asignar a df.columns o usar .set_axis() es más rápido que construir un diccionario con todos los mapeos antiguo→nuevo. Y si el renombrado sigue una regla (quitar espacios, poner todo en minúsculas, convertir camelCase), pasar una función o usar el accesor .str te permite expresar la regla una sola vez. Polars resuelve lo mismo con una API similar, pero su estilo inmutable y de encadenado te lleva a otros hábitos. 

Para seguir mejorando tus habilidades con DataFrame, te recomiendo el curso Data Manipulation with pandas como siguiente paso. Si quieres una ruta de aprendizaje estructurada, el itinerario Data Analyst in Python cubre la manipulación de DataFrames junto al resto del toolkit de analista.