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.
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:
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_exceldevuelve un DataFrame. Ideal para análisis, pero descarta todo el formato.openpyxl.load_workbookpreserva el formato y te da objetos celda. Más lento en archivos grandes.pd.ExcelWriterconengine="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=TruedevuelveNoneen 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ía | Nivel | Mejor Para | Dependencias |
|---|---|---|---|
| pandas | DataFrame | Análisis de datos, lectura/escritura masiva | pandas, openpyxl |
| openpyxl | Celda | Formato, fórmulas, gráficos | openpyxl |
| xlsxwriter | Celda | Reportes de solo escritura, gráficos, formato condicional | xlsxwriter |
| python-calamine | DataFrame | Lecturas rápidas como engine de pandas | python-calamine |
| xlrd | Solo lectura | Archivos .xls legacy | xlrd |
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=Falseato_excelsalvo 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_panesyauto_filtera los reportes que alguien va a abrir; cuestan dos líneas y hacen usable una hoja grande. - Usa el context manager de
pd.ExcelWriterpara 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_workbooka secas. Usaread_only=Trueen archivos que no entren cómodos en memoria. - Esperar que
data_only=Truedevuelva 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; usaExcelWriterconmode="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:
.xlsxes 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
.xlsmpueden llevar código VBA. Elkeep_vba=Truede 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
- Documentación de openpyxl — la API completa de estilos, gráficos y funciones de workbook.
- Referencia de
read_excelde pandas — engines, selección de hojas y control de dtypes. - Changelog de xlrd 2.0 — explica por qué el xlrd moderno solo lee
.xls.
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.
Recursos Relacionados
Analizar Archivos Excel en Python, JavaScript y Java
Cómo leer y escribir archivos Excel (.xlsx) en Python, JavaScript y Java con openpyxl, SheetJS y Apache POI.
RecipeImportar Datos desde CSV/Excel
Cómo parsear e importar datos desde archivos CSV y Excel con validación, streaming e inserción por lotes.
RecipeExportar Datos a CSV y Excel
Cómo exportar datos estructurados a archivos CSV y Excel de forma eficiente.
RecipeLeer Archivos CSV con Python y Pandas
Cómo leer, filtrar y transformar archivos CSV grandes de forma eficiente con pandas y el módulo csv de Python.
RecipeConvertir CSV a JSON
Convertí archivos CSV a JSON estructurado con Python, JavaScript y Java. Elegí la librería adecuada para conversiones puntuales o pipelines grandes.
RecipeGenerar Reportes PDF en Python: Guía de ReportLab y fpdf2
Crea documentos PDF con estilos a partir de datos usando ReportLab y fpdf2 en Python.