StackPractices
intermediate Por Mathias Paulenko

Leer y Escribir Excel en Python (openpyxl + pandas)

Cómo leer, escribir y formatear hojas de cálculo Excel en Python con pandas y openpyxl, con ejemplos listos para copiar.

Temas: data

Visión General

Los archivos Excel (.xlsx) están en todos los flujos de trabajo empresariales: exportaciones de CRM, reportes financieros, inventarios. Python los maneja bien con dos librerías: pandas para trabajo centrado en datos y openpyxl para control a nivel de celda, como formato y fórmulas. Esta recipe cubre ambos enfoques para las tareas habituales: leer hojas, escribir datos, dar estilo a un reporte y trabajar con workbooks demasiado grandes para cargarlos de una vez.

Cuándo Usar

  • Necesitas cargar exportaciones Excel de herramientas de negocio en un DataFrame para analizarlas
  • Generas reportes Excel desde una base de datos o API y necesitan estilo (colores, formatos numéricos, anchos de columna)
  • Automatizas un flujo que produce o consume varias hojas dentro de un mismo workbook
  • Necesitas agregar datos a un archivo existente sin destruir su formato

No aplica cuando la fuente ya es una base de datos (consúltala directamente en lugar de pasar por Excel) o cuando solo necesitas mirar los datos una vez. Para archivos planos, consulta Parsear CSV con Python y Pandas: el CSV se parsea mucho más rápido.

Cómo elegir la librería correcta:

flowchart diagram: Tarea con Excel

Solución

Los snippets de abajo están listos para copiar. Una versión ejecutable con todos los ejemplos está en el repositorio complementario.

Instala ambas librerías. pandas usa openpyxl como engine para archivos .xlsx, así que un openpyxl ausente es el fallo de instalación más común.

pip install pandas openpyxl

Leer Excel con pandas

import pandas as pd

# Leer una sola hoja
df = pd.read_excel("data.xlsx", sheet_name="Sheet1")
print(df.head())
print(df.columns)

# Leer todas las hojas a un dict de DataFrames
sheets = pd.read_excel("data.xlsx", sheet_name=None)
for name, df in sheets.items():
    print(f"Sheet: {name}, rows: {len(df)}")

Escribir Excel con pandas

import pandas as pd

df = pd.DataFrame({
    "name": ["Alice", "Bob", "Charlie"],
    "score": [85, 92, 78],
})

# Escritura básica
df.to_excel("output.xlsx", index=False, sheet_name="Results")

# Múltiples hojas
with pd.ExcelWriter("report.xlsx") as writer:
    df.to_excel(writer, sheet_name="Summary", index=False)
    df[df["score"] > 80].to_excel(writer, sheet_name="High Scores", index=False)

Control a nivel de celda con openpyxl

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side

wb = Workbook()
ws = wb.active
ws.title = "Report"

# Fila de encabezado con estilos
headers = ["Name", "Score", "Grade"]
header_fill = PatternFill(start_color="1a56db", end_color="1a56db", fill_type="solid")
header_font = Font(color="FFFFFF", bold=True)
thin_bottom = Border(bottom=Side(style="thin", color="1a56db"))

for col, header in enumerate(headers, 1):
    cell = ws.cell(row=1, column=col, value=header)
    cell.fill = header_fill
    cell.font = header_font
    cell.border = thin_bottom
    cell.alignment = Alignment(horizontal="center")

# Filas de datos
data = [("Alice", 85, "B"), ("Bob", 92, "A"), ("Charlie", 78, "C")]
for row_idx, (name, score, grade) in enumerate(data, 2):
    ws.cell(row=row_idx, column=1, value=name)
    ws.cell(row=row_idx, column=2, value=score)
    ws.cell(row=row_idx, column=3, value=grade)

# Auto-ajustar columnas (openpyxl no lo hace por ti)
for col in ws.columns:
    max_length = max(len(str(cell.value or "")) for cell in col)
    ws.column_dimensions[col[0].column_letter].width = max_length + 2

# Congelar el encabezado y agregar filtro para legibilidad
ws.freeze_panes = "A2"
ws.auto_filter.ref = ws.dimensions

wb.save("formatted_report.xlsx")

Leer con openpyxl

from openpyxl import load_workbook

wb = load_workbook("data.xlsx", data_only=True)  # data_only lee los valores cacheados
ws = wb["Sheet1"]

for row in ws.iter_rows(min_row=1, max_row=5, values_only=True):
    print(row)

# Acceder a una celda específica
print(ws["A1"].value)

Agregar fórmulas

from openpyxl import Workbook

wb = Workbook()
ws = wb.active

ws["A1"] = 10
ws["A2"] = 20
ws["A3"] = 30
ws["A4"] = "=SUM(A1:A3)"
ws["A5"] = "=AVERAGE(A1:A3)"

wb.save("formulas.xlsx")

Explicación

pandas usa openpyxl por debajo al leer y escribir archivos .xlsx. Usa pandas para operaciones centradas en datos (filtrado, agrupación, joins) y openpyxl cuando necesitas control a nivel de celda (formato, fórmulas, celdas combinadas, gráficos). Para una visión general multilenguaje de la misma tarea en Java y JavaScript, consulta Parsear Archivos Excel.

Diferencias clave:

  • pd.read_excel devuelve un DataFrame. Ideal para análisis, pero descarta todo el formato.
  • openpyxl.load_workbook preserva el formato y te da objetos celda. Más lento en archivos grandes.
  • pd.ExcelWriter con engine="openpyxl" escribe DataFrames conservando el formato de un workbook existente.

Dos salvedades sobre fórmulas que a todos nos muerden al menos una vez:

  • openpyxl escribe las fórmulas como texto pero nunca las calcula. =SUM(A1:A3) queda guardada como cadena hasta que Excel (o LibreOffice) abre el archivo y la evalúa.
  • data_only=True devuelve None en las celdas con fórmula si el archivo nunca fue abierto y guardado por una aplicación de hojas de cálculo real: los archivos generados por openpyxl no tienen valores cacheados que leer. Si necesitas el resultado calculado, calcúlalo en Python en lugar de escribir una fórmula.

Trabajar con Archivos Grandes

openpyxl carga el workbook entero en memoria. Un .xlsx de 50MB puede consumir más de 500MB de RAM, un problema en servidores pequeños o runners de CI. Hay dos vías de escape:

from openpyxl import load_workbook

# Lectura en streaming: las filas se generan una a una, no se cargan todas
wb = load_workbook("big.xlsx", read_only=True, data_only=True)
ws = wb["Sheet1"]

for row in ws.iter_rows(values_only=True):
    process(row)

wb.close()  # importante en modo read_only: libera el handle del archivo

Para escribir, Workbook(write_only=True) vuelca las celdas a disco con el mismo beneficio de memoria — pierdes acceso aleatorio (solo puedes agregar filas), pero archivos de cientos de miles de filas se vuelven viables.

Cuando la velocidad importa más que el formato, pd.read_excel(..., engine="calamine") (pandas 2.2+, requiere el paquete python-calamine) es un lector basado en Rust notablemente más rápido que el engine openpyxl. Y si el archivo es solo una fuente de datos —no algo que una persona vaya a abrir— convertirlo primero a CSV o Parquet es casi siempre la decisión correcta.

Agregar a un Workbook Existente

df.to_excel("report.xlsx") reemplaza el archivo completo. Para añadir una hoja a un workbook que ya existe, ábrelo en modo append:

import pandas as pd

new_rows = pd.DataFrame({"name": ["Dana"], "score": [95]})

with pd.ExcelWriter(
    "report.xlsx", mode="a", engine="openpyxl", if_sheet_exists="replace"
) as writer:
    new_rows.to_excel(writer, sheet_name="Summary", index=False)

if_sheet_exists acepta "replace" (reescribe esa hoja), "overlay" (escribe sobre las celdas existentes), "new" (crea Summary1) o "error". Las demás hojas y su formato quedan intactos.

Variantes

LibreríaNivelMejor ParaDependencias
pandasDataFrameAnálisis de datos, lectura/escritura masivapandas, openpyxl
openpyxlCeldaFormato, fórmulas, gráficosopenpyxl
xlsxwriterCeldaReportes de solo escritura, gráficos, formato condicionalxlsxwriter
python-calamineDataFrameLecturas rápidas como engine de pandaspython-calamine
xlrdSolo lecturaArchivos .xls legacyxlrd

Si necesitas exportar los mismos datos a CSV o Excel desde una aplicación, Exportar CSV y Excel cubre ese flujo; Importar CSV y Excel cubre el lado de la subida de archivos.

Buenas Prácticas

  • Usa pandas para leer y escribir datos; usa openpyxl para formato y fórmulas.
  • Pasa siempre index=False a to_excel salvo que realmente necesites la columna de índice.
  • Lee los resultados de fórmulas con data_only=True, y calcula en Python cuando la caché no exista.
  • Define los anchos de columna explícitamente: openpyxl no los auto-ajusta.
  • Agrega freeze_panes y auto_filter a los reportes que alguien va a abrir; cuestan dos líneas y hacen usable una hoja grande.
  • Usa el context manager de pd.ExcelWriter para que el archivo siempre se cierre y se escriba a disco.
  • Mantén los formatos numéricos explícitos (cell.number_format = "0.00", "yyyy-mm-dd") cuando la presentación importa.

Errores Comunes

  • Olvidar instalar openpyxl. pandas lo necesita como engine para archivos .xlsx.
  • Cargar un workbook enorme con load_workbook a secas. Usa read_only=True en archivos que no entren cómodos en memoria.
  • Esperar que data_only=True devuelva valores en un archivo escrito por openpyxl: la caché no existe hasta que una aplicación de hojas de cálculo lo guarde.
  • Sobrescribir un workbook existente con to_excel. Reemplaza el archivo; usa ExcelWriter con mode="a" para agregar.
  • Asumir que openpyxl evalúa fórmulas. Las escribe; no las calcula.
  • Ignorar los formatos numéricos: Excel puede mostrar fechas y decimales distinto de lo que Python produce.
  • Escribir a un archivo que alguien tiene abierto en Excel. En Windows eso lanza PermissionError; guarda con otro nombre o captura el error.

Consideraciones de Seguridad

Los archivos Excel merecen una revisión de seguridad breve cuando cruzan un límite de confianza (subidas de usuarios, archivos enviados a terceros):

  • Inyección de fórmulas: un valor de celda que empieza con =, +, - o @ se ejecuta como fórmula cuando alguien abre el archivo en Excel. Si escribes datos controlados por el usuario en un workbook, prefija las cadenas riesgosas con ' o recházalas: es la clásica inyección CSV, y también aplica a .xlsx.
  • Zip bombs: .xlsx es un contenedor zip, así que una subida pequeña puede descomprimirse en gigabytes de XML. Aplica un límite de tamaño a los uploads antes de parsearlos.
  • Macros: los .xlsm pueden llevar código VBA. El keep_vba=True de openpyxl preserva las macros pero nunca las ejecuta; aun así, no reenvíes archivos con macros a usuarios finales sin motivo.
  • Nunca uses eval() con nada leído de un workbook. Trata los valores de celda como cadenas no confiables.

Ver También

Preguntas frecuentes

¿Debo usar pandas u openpyxl?

pandas para todo lo que parezca análisis de datos: filtrar, agregar, hacer joins, exportaciones masivas. openpyxl cuando necesites controlar el archivo en sí: estilos de celda, fórmulas, celdas combinadas, gráficos o editar una plantilla existente.

¿Cómo instalo las librerías?

pip install pandas openpyxl. pandas llama a openpyxl para el soporte de .xlsx, así que necesitas ambas.

¿Cómo leo un rango específico de celdas?

Con openpyxl, usa ws.iter_rows(min_row=2, max_row=10, min_col=1, max_col=3, values_only=True). Con pandas, usa los parámetros usecols y skiprows de read_excel.

¿Cómo agrego formato condicional?

Usa openpyxl.formatting.rule o xlsxwriter. Las escalas de color y las barras de datos están soportadas con ColorScaleRule y DataBarRule.

¿Cómo agrego filas a un archivo Excel existente?

Ábrelo con pd.ExcelWriter(path, mode="a", engine="openpyxl", if_sheet_exists="replace") y escribe la hoja nueva: el resto de hojas y el formato se conservan. Para ediciones a nivel de fila, carga el workbook con openpyxl y escribe en celdas concretas.

¿Cómo manejo archivos .xls (legacy)?

Usa xlrd para leer y xlwt para escribir. pandas los soporta con engine="xlrd" y engine="xlwt". Ten en cuenta que xlrd dejó de soportar .xlsx en la versión 2.0: para archivos antiguos necesitas xlrd<2.0 o python-calamine.

¿Puedo crear gráficos en Excel con Python?

Sí. openpyxl.chart soporta gráficos de barras, líneas y pie. xlsxwriter también soporta gráficos con una API similar: no puede leer archivos, pero suele ser la mejor opción para reportes pulidos de solo escritura.