Explorar guías rápidas · Python
Depurar problemas comunes de pandas
Diagnostica fallos comunes de pandas relacionados con dtypes, valores faltantes, joins, asignación encadenada, datos duplicados, errores de fechas, presión de memoria y cambios inesperados en el número de filas.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Depurar un KeyError por una columna que falta
- 2. Depurar mayúsculas incorrectas o columnas renombradas
- 3. Depurar fallos de conversión numérica
- 4. Depurar nulos inesperados después de una conversión
- 5. Depurar fallos al analizar fechas
- 6. Depurar errores al comparar fechas con y sin zona horaria (aware vs naive)
- 7. Depurar filtros que no devuelven filas
- 8. Depurar errores en filtros booleanos
- 9. Depurar problemas de asignación encadenada
- 10. Depurar un aumento inesperado de filas después de un merge
- 11. Depurar coincidencias que faltan después de un merge
- 12. Depurar filas duplicadas
- 13. Depurar totales inflados después de un join
- 14. Depurar cambios inesperados de dtype después de ingerir un CSV
- 15. Depurar columnas enteras que se convierten en float
- 16. Depurar columnas object que deberían ser numéricas
- 17. Depurar ValueError: cannot convert float NaN to integer
- 18. Depurar SettingWithCopyWarning / la confusión con copy-on-write
- 19. Depurar totales de groupby() que parecen incorrectos
- 20. Depurar grupos que faltan en groupby()
- 21. Depurar una lógica incorrecta de «última fila»
- 22. Depurar un .apply() lento
- 23. Depurar el uso de memoria
- 24. Reducir la memoria antes de un merge grande
- 25. Depurar ordenaciones inesperadamente lentas
- 26. Depurar filas de CSV que se desplazan a columnas incorrectas
- 27. Depurar líneas de CSV mal formadas
- 28. Depurar una estructura JSON inesperada
- 29. Depurar resultados comparando invariantes
- 30. Crear una función auxiliar reutilizable para diagnosticar DataFrames
- Qué significa el resultado
- Qué revisar
- El número de filas cambia de forma inesperada
- El número de nulos aumenta de forma inesperada
- El dtype cambia de forma inesperada
- Los totales cambian después de un enriquecimiento
- Los datos se ven bien en head() pero las métricas son incorrectas
- Una solución provisional «arregla» el error pero oculta el motivo
- Notas de producción
- Depura con muestras pequeñas y representativas
- Registra los cambios de esquema y de número de filas
- Evita modificar muchas cosas a la vez
- Conserva los registros incorrectos para analizarlos
- Las excepciones pueden ser más seguras que la coerción silenciosa
- pandas es una herramienta en memoria
- Errores comunes
- 1. Corregir síntomas en lugar de causas
- 2. Depurar solo el DataFrame final
- 3. Confiar en head()
- 4. Ignorar la granularidad de negocio
- 5. Ignorar los dtypes
- 6. Suprimir advertencias a ciegas
- 7. Usar errors="coerce" sin medir el impacto
- 8. Eliminar automáticamente las filas de entrada mal formadas
- 9. Depurar el rendimiento antes que la corrección
- Siguiente paso
- Para profundizar
Problema
Un flujo de trabajo de pandas falla, produce un número de filas incorrecto, cambia los dtypes de forma inesperada, crea valores faltantes o devuelve resultados que no coinciden con la lógica de negocio.
Entre los síntomas comunes están:
KeyErrorValueErrordurante una conversión- fallos de merge/join
- filas duplicadas inesperadas
- nulos inesperados
- advertencias de asignación encadenada (chained assignment)
- errores al comparar fechas
- errores de memoria
- dtype
objectdonde se esperaban datos numéricos o de fecha - totales que cambian después de un merge
- filtros que devuelven cero filas
El objetivo es aislar el fallo rápidamente sin ocultar el problema de datos subyacente.
Respuesta rápida
Empieza con una pasada de diagnóstico compacta:
print("Shape:", df.shape)
print("\nColumns:")
print(df.columns.tolist())
print("\nDtypes:")
print(df.dtypes)
print("\nNulls:")
print(
df.isna()
.sum()
.sort_values(ascending=False)
.head(20)
)
print("\nDuplicates:")
print(df.duplicated().sum())
print("\nSample:")
print(df.head())
Después pregúntate:
¿Cambió el número de filas?
¿Cambió el dtype?
¿Cambió el número de nulos?
¿Cambió la unicidad de la clave?
¿La operación conservó la granularidad prevista?
La mayoría de los bugs de pandas son más fáciles de resolver en cuanto comparas el DataFrame justo antes y justo después de la transformación que falla.
Código / comandos
1. Depurar un KeyError por una columna que falta
Comprueba los nombres exactos de las columnas:
print(df.columns.tolist())
Busca espacios en blanco:
for col in df.columns:
print(repr(col))
Si la fuente contiene espacios accidentales:
df.columns = (
df.columns
.str.strip()
)
No normalices los nombres de columna a ciegas si hay contratos externos que dependen de los nombres exactos.
2. Depurar mayúsculas incorrectas o columnas renombradas
Comprueba:
print(df.columns)
Las diferencias de mayúsculas y minúsculas importan:
CustomerID
customerid
customer_id
son nombres de columna distintos.
Si necesitas nombres normalizados, hazlo una sola vez en la ingesta y deja ese esquema explícito.
3. Depurar fallos de conversión numérica
En lugar de:
df["amount"] = df["amount"].astype(float)
usa:
parsed = pd.to_numeric(
df["amount"],
errors="coerce",
)
Encuentra los valores que fallaron:
failed = df.loc[
df["amount"].notna()
& parsed.isna(),
"amount",
]
print(
failed
.value_counts()
.head(20)
)
Causas típicas:
- comas
- símbolos de moneda
- etiquetas de texto
- cadenas vacías
- valores centinela
- registros de origen mal formados
4. Depurar nulos inesperados después de una conversión
Mide antes y después:
before_nulls = df["amount"].isna().sum()
parsed = pd.to_numeric(
df["amount"],
errors="coerce",
)
after_nulls = parsed.isna().sum()
print(
"New nulls:",
after_nulls - before_nulls,
)
Los nuevos nulos inesperados indican que algunos valores de origen no se pudieron convertir.
No sigas adelante en silencio.
5. Depurar fallos al analizar fechas
Analiza los valores en una Series temporal:
parsed = pd.to_datetime(
df["event_time"],
errors="coerce",
)
Encuentra los fallos:
failed = df.loc[
df["event_time"].notna()
& parsed.isna(),
"event_time",
]
print(
failed
.value_counts()
.head(20)
)
Busca:
- formatos mezclados
- fechas no válidas
- texto de zona horaria
- ambigüedad entre día y mes
- cambios inesperados en el origen
6. Depurar errores al comparar fechas con y sin zona horaria (aware vs naive)
Inspecciona ambos lados:
print(df["event_time"].dtype)
print(start_time)
print(start_time.tzinfo)
Si la Series está en UTC con zona horaria:
df["event_time"] = pd.to_datetime(
df["event_time"],
utc=True,
errors="coerce",
)
Después usa un límite de comparación con zona horaria:
start_time = pd.Timestamp(
"2026-10-01",
tz="UTC",
)
No compares marcas de tiempo con y sin zona horaria sin decidir qué zona horaria representa el valor sin zona.
7. Depurar filtros que no devuelven filas
Empieza por comprobar los valores reales:
print(
df["status"]
.value_counts(dropna=False)
.head(20)
)
Inspecciona los valores normalizados:
normalized = (
df["status"]
.astype("string")
.str.strip()
.str.casefold()
)
print(
normalized
.value_counts(dropna=False)
.head(20)
)
Causas frecuentes:
- espacios en blanco
- mayúsculas y minúsculas
- nulos
- incompatibilidad de dtype
- códigos inesperados
- límites de fecha incorrectos
8. Depurar errores en filtros booleanos
Incorrecto:
df[
df["amount"] > 100
and df["status"] == "active"
]
Correcto:
df.loc[
(df["amount"] > 100)
& (df["status"] == "active")
]
Para Series de pandas, usa:
&|~
y pon cada condición entre paréntesis.
9. Depurar problemas de asignación encadenada
Arriesgado:
df[df["amount"] > 100]["flag"] = True
Usa:
df.loc[
df["amount"] > 100,
"flag",
] = True
Si quieres intencionadamente un DataFrame filtrado independiente:
subset = df.loc[
df["amount"] > 100
].copy()
subset["flag"] = True
Deja explícito a quién pertenecen los datos en lugar de depender de vistas/copias ambiguas.
10. Depurar un aumento inesperado de filas después de un merge
Mide antes y después:
before = len(left)
result = left.merge(
right,
on="customer_id",
how="left",
)
after = len(result)
print("Before:", before)
print("After:", after)
print("Added rows:", after - before)
Si un left join de enriquecimiento crece de forma inesperada, inspecciona los duplicados del lado derecho:
duplicate_right_keys = right.loc[
right["customer_id"]
.duplicated(keep=False)
].sort_values("customer_id")
print(duplicate_right_keys)
Usa la validación de cardinalidad:
result = left.merge(
right,
on="customer_id",
how="left",
validate="many_to_one",
)
11. Depurar coincidencias que faltan después de un merge
Usa indicator=True:
result = left.merge(
right,
on="customer_id",
how="left",
indicator=True,
)
Inspecciona las filas sin coincidencia:
unmatched = result.loc[
result["_merge"] == "left_only"
]
print(unmatched.head(50))
Después compara los dtypes de las claves:
print(left["customer_id"].dtype)
print(right["customer_id"].dtype)
Comprueba el formato:
print(
left["customer_id"]
.astype("string")
.str.strip()
.head()
)
12. Depurar filas duplicadas
Comprueba los duplicados de fila completa:
print(df.duplicated().sum())
Comprueba los duplicados de la clave de negocio:
key_cols = [
"customer_id",
"order_id",
]
duplicates = df.loc[
df.duplicated(
subset=key_cols,
keep=False,
)
].sort_values(key_cols)
print(duplicates)
No llames a drop_duplicates() antes de definir cuál debe ser la clave de negocio.
13. Depurar totales inflados después de un join
Antes del join:
source_total = left["amount"].sum()
Después:
result_total = result["amount"].sum()
print("Before:", source_total)
print("After:", result_total)
Si el total aumentó, inspecciona:
- claves duplicadas en el lado derecho
- una clave compuesta incorrecta
- una expansión many-to-many
- filas duplicadas en el lado izquierdo
No vuelvas a agregar el total hasta entender la multiplicación de filas.
14. Depurar cambios inesperados de dtype después de ingerir un CSV
Inspecciona:
print(df.dtypes)
Si un identificador se convirtió en numérico, vuelve a cargarlo con un dtype explícito:
df = pd.read_csv(
"orders.csv",
dtype={
"customer_id": "string",
},
)
CSV no incluye un esquema.
La inferencia no es un contrato de datos.
15. Depurar columnas enteras que se convierten en float
Esto suele ocurrir porque los valores faltantes no se pueden representar con el dtype entero de NumPy.
Usa los enteros que admiten nulos de pandas:
df["quantity"] = (
pd.to_numeric(
df["quantity"],
errors="coerce",
)
.astype("Int64")
)
Ahora los valores faltantes pueden coexistir con la semántica de enteros.
16. Depurar columnas object que deberían ser numéricas
Inspecciona los tipos de Python de los valores:
print(
df["amount"]
.dropna()
.map(type)
.value_counts()
)
Después inspecciona los valores incorrectos únicos mediante la conversión:
parsed = pd.to_numeric(
df["amount"],
errors="coerce",
)
bad = df.loc[
df["amount"].notna()
& parsed.isna(),
"amount",
]
print(
bad
.value_counts()
.head(20)
)
17. Depurar ValueError: cannot convert float NaN to integer
No uses:
df["quantity"].astype(int)
si existen nulos.
Usa:
df["quantity"] = (
df["quantity"]
.astype("Int64")
)
o decide primero si los valores faltantes deben rellenarse o rechazarse.
18. Depurar SettingWithCopyWarning / la confusión con copy-on-write
Prefiere una selección y una asignación explícitas:
mask = df["status"].eq("active")
df.loc[
mask,
"flag",
] = True
Para subconjuntos independientes:
active = df.loc[
mask
].copy()
Las versiones modernas de pandas usan cada vez más la semántica copy-on-write, pero .loc[] y .copy() explícitos siguen dejando más clara la intención y evitan código frágil.
19. Depurar totales de groupby() que parecen incorrectos
Comprueba primero la granularidad de entrada.
print(
df.duplicated(
subset=["order_id"]
).sum()
)
Después compara el número de filas con el número de valores distintos:
print("Rows:", len(df))
print(
"Unique orders:",
df["order_id"].nunique(),
)
Si un pedido aparece varias veces por un join anterior, una suma simple puede contar dos veces los ingresos.
20. Depurar grupos que faltan en groupby()
Las claves de agrupación nulas suelen ser la causa.
Compara:
summary_default = (
df.groupby("country")
.size()
)
con:
summary_with_nulls = (
df.groupby(
"country",
dropna=False,
)
.size()
)
Si ahora los totales cuadran, las claves de agrupación faltantes se estaban excluyendo.
21. Depurar una lógica incorrecta de «última fila»
Patrón incorrecto:
latest = (
df.groupby("customer_id")
.max()
)
Esto puede combinar máximos de filas distintas.
Correcto:
latest = (
df.sort_values(
[
"customer_id",
"event_time",
"event_id",
],
ascending=[
True,
False,
False,
],
)
.drop_duplicates(
subset=["customer_id"],
keep="first",
)
)
Define un criterio de desempate determinista.
22. Depurar un .apply() lento
Busca código fila por fila como:
df["result"] = df.apply(
expensive_function,
axis=1,
)
Prueba primero alternativas vectorizadas.
Ejemplo:
df["result"] = (
df["amount"]
* df["quantity"]
)
Para condiciones:
df["is_large"] = (
df["amount"] > 1000
)
Usa .apply() cuando la lógica realmente no se pueda expresar de forma vectorizada.
23. Depurar el uso de memoria
Empieza con:
df.info(
memory_usage="deep",
)
Por columna:
memory = (
df.memory_usage(
deep=True,
)
.sort_values(
ascending=False,
)
)
print(memory)
Busca:
- columnas object/de cadenas grandes
- columnas sin usar
- texto de alta cardinalidad
- DataFrames intermedios duplicados
24. Reducir la memoria antes de un merge grande
Selecciona solo las columnas necesarias:
left_small = left[
[
"customer_id",
"order_id",
"amount",
]
]
right_small = right[
[
"customer_id",
"segment",
]
]
Después haz el merge:
result = left_small.merge(
right_small,
on="customer_id",
how="left",
validate="many_to_one",
)
Evita arrastrar decenas de columnas sin usar por operaciones costosas.
25. Depurar ordenaciones inesperadamente lentas
Si solo necesitas las primeras filas:
top_10 = df.nlargest(
10,
"revenue",
)
en lugar de:
top_10 = (
df.sort_values(
"revenue",
ascending=False,
)
.head(10)
)
Para un top N por grupo, ordena solo después de filtrar y seleccionar las columnas necesarias.
26. Depurar filas de CSV que se desplazan a columnas incorrectas
Inspecciona el archivo sin procesar y tus suposiciones sobre el delimitador.
Prueba:
df = pd.read_csv(
"data.csv",
sep=",",
)
Si la fuente usa otro delimitador:
df = pd.read_csv(
"data.csv",
sep=";",
)
Investiga también:
- delimitadores incrustados en los valores
- comillas
- filas mal formadas
- codificación
No uses un análisis permisivo para ocultar registros de origen corruptos sin medir qué se omitió o se modificó.
27. Depurar líneas de CSV mal formadas
Si necesitas identificar temporalmente problemas de análisis, aísla el archivo defectuoso en lugar de aceptar en silencio una pérdida de datos.
Una lectura de diagnóstico puede usar:
df = pd.read_csv(
"data.csv",
on_bad_lines="warn",
)
Esto es útil durante la investigación.
En producción, decide de forma deliberada si los registros mal formados deben:
- hacer fallar la carga
- ponerse en cuarentena
- corregirse en el origen
No pongas skip como opción predeterminada solo para mantener un pipeline en verde.
28. Depurar una estructura JSON inesperada
Inspecciona la estructura sin procesar antes de normalizarla.
print(type(payload))
Si está anidada:
df = pd.json_normalize(
payload["results"]
)
Si los arrays se expanden en varias filas, verifica la granularidad prevista.
Por ejemplo:
una fila por pedido
es distinto de:
una fila por artículo del pedido
29. Depurar resultados comparando invariantes
Antes de una transformación:
before = {
"rows": len(df),
"orders": df["order_id"].nunique(),
"revenue": df["amount"].sum(),
}
Después:
after = {
"rows": len(result),
"orders": result["order_id"].nunique(),
"revenue": result["amount"].sum(),
}
print("Before:", before)
print("After:", after)
Elige los invariantes según la operación.
Ejemplos:
- left join de enriquecimiento → puede que el número de filas y los totales deban mantenerse iguales
- deduplicación → el número de filas cambia intencionadamente
- filtrado → los totales deberían disminuir de forma predecible
- agregación → el número de filas cambia, pero los totales pueden cuadrar
30. Crear una función auxiliar reutilizable para diagnosticar DataFrames
def diagnose_df(
df: pd.DataFrame,
key_cols: list[str] | None = None,
) -> None:
print("Shape:", df.shape)
print("\nDtypes:")
print(df.dtypes)
print("\nNulls:")
print(
df.isna()
.sum()
.sort_values(
ascending=False,
)
.head(20)
)
print(
"\nDuplicate rows:",
df.duplicated().sum(),
)
if key_cols:
print(
"\nDuplicate keys:",
df.duplicated(
subset=key_cols
).sum(),
)
print("\nSample:")
print(df.head())
Usa funciones auxiliares como esta para la resolución de problemas en local.
Para pipelines de producción, prefiere logs estructurados y métricas de calidad de datos.
Qué significa el resultado
Un bug de pandas suele encajar en una de estas categorías:
| Síntoma | Área probable |
|---|---|
KeyError |
esquema / nombres de columna |
| excepción de conversión | valores sin procesar incompatibles |
| nuevos nulos | fallo de análisis o de join |
| filas de más después de un merge | cardinalidad incorrecta / claves duplicadas |
| filas que faltan después de un merge | claves sin coincidencia / comportamiento de inner join |
| totales incorrectos | granularidad duplicada / agregación / expansión del join |
| «última» fila incorrecta | lógica de ordenación/desempate |
dtype object |
datos de origen mezclados o con tipado laxo |
| advertencia de asignación encadenada | ruta de modificación ambigua |
| error al comparar fechas | incompatibilidad de zona horaria o de dtype |
| presión de memoria | DataFrame/intermedios/columnas object demasiado grandes |
.apply() lento |
ejecución de Python fila por fila |
El patrón de depuración importante es:
inspeccionar
→ aislar
→ comparar antes/después
→ validar las suposiciones
→ cambiar una sola cosa
→ volver a comprobar
Qué revisar
El número de filas cambia de forma inesperada
Es una de las señales más claras de un problema de lógica.
Comprueba:
- la cardinalidad del merge
- los filtros
- las claves duplicadas
- explode/la normalización
- la deduplicación
El número de nulos aumenta de forma inesperada
Comprueba:
- las conversiones fallidas
- los joins sin coincidencia
- las columnas de origen que faltan
- las reglas de análisis
El dtype cambia de forma inesperada
Comprueba:
- la inferencia de CSV
- los valores faltantes
- la concatenación
- los merges
- la lógica de conversión
Los totales cambian después de un enriquecimiento
Es probable que haya una expansión many-to-many o one-to-many.
Valida las claves del join antes de continuar.
Los datos se ven bien en head() pero las métricas son incorrectas
head() no es representativo.
Usa:
- conteos
- conteos de valores distintos
- resúmenes de nulos
- distribuciones
- totales de conciliación
Una solución provisional «arregla» el error pero oculta el motivo
Ejemplos:
errors="coerce"
drop_duplicates()
fillna(0)
on_bad_lines="skip"
Pueden ser herramientas útiles, pero no deberían convertirse en una forma automática de suprimir errores.
Notas de producción
Depura con muestras pequeñas y representativas
Para flujos de trabajo costosos:
sample = df.sample(
min(10_000, len(df)),
random_state=42,
)
Usa muestras para iterar y después valida la lógica final con los datos completos.
No uses una muestra para demostrar la unicidad ni la calidad completa de los datos.
Registra los cambios de esquema y de número de filas
Los pipelines de producción deberían registrar como mínimo:
- el número de filas de entrada
- el número de filas de salida
- el número de valores distintos de la clave
- el número de nulos en las columnas importantes
- los totales de negocio importantes
- el esquema/los dtypes
Así, una deriva silenciosa de los datos se convierte en un comportamiento observable.
Evita modificar muchas cosas a la vez
Patrón de depuración incorrecto:
limpiar cadenas
convertir tipos
eliminar nulos
hacer merge
deduplicar
agregar
todo en una sola cadena.
Durante la investigación, separa las transformaciones y valida después de cada etapa.
Conserva los registros incorrectos para analizarlos
Cuando sea posible, pon en cuarentena las filas no válidas en lugar de descartarlas.
Ejemplo:
valid = parsed.notna()
good_rows = df.loc[valid].copy()
bad_rows = df.loc[~valid].copy()
Así se conserva la evidencia.
Las excepciones pueden ser más seguras que la coerción silenciosa
Con contratos de producción estrictos, dejar que un pipeline falle puede ser mejor que cambiar en silencio los datos incorrectos.
Elige el manejo de errores según el requisito de fiabilidad.
pandas es una herramienta en memoria
Si el problema es principalmente de memoria o de escala, puede que la solución no sea otro truco de pandas.
Considera:
- SQL
- DuckDB
- PyArrow
- Spark
- PySpark
- una base de datos/un data warehouse
según la carga de trabajo y la arquitectura.
Errores comunes
1. Corregir síntomas en lugar de causas
Ejemplos como:
drop_duplicates()
fillna(0)
astype(str)
pueden ocultar problemas de datos más profundos.
Entiende primero por qué los datos son incorrectos.
2. Depurar solo el DataFrame final
Inspecciona las etapas intermedias.
La transformación que cambia primero el número de filas, el dtype, los nulos o la granularidad suele ser donde empieza el bug.
3. Confiar en head()
Unas pocas filas no bastan para validar un conjunto de datos.
Usa diagnósticos agregados.
4. Ignorar la granularidad de negocio
Muchos bugs de pandas son en realidad problemas de granularidad.
Define:
¿Qué debería representar una fila?
antes de los merges, las agregaciones o la deduplicación.
5. Ignorar los dtypes
Una incompatibilidad entre cadena y entero puede romper joins y filtros sin diferencias visuales evidentes.
6. Suprimir advertencias a ciegas
Las advertencias suelen revelar un comportamiento frágil.
Entiéndelas antes de desactivarlas.
7. Usar errors="coerce" sin medir el impacto
Puede convertir en silencio valores no válidos en valores faltantes.
Haz seguimiento de los nulos nuevos.
8. Eliminar automáticamente las filas de entrada mal formadas
Omitir líneas incorrectas puede dejar mal el número de filas y los totales mientras el pipeline sigue pareciendo correcto.
9. Depurar el rendimiento antes que la corrección
Asegúrate primero de que el resultado sea correcto.
Después optimiza.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.