Pandas Merge: La guía completa para combinar DataFrames en Python

Name

Soren Atelier

Updated on 9/2/2026

Trabajar con un solo DataFrame es raro en el mundo real. La mayoría de los proyectos de análisis de datos requieren combinar datos de múltiples fuentes: registros de ventas con perfiles de clientes, lecturas de sensores con metadatos de dispositivos, o respuestas de encuestas con tablas demográficas. La función pandas merge es la herramienta estándar que los desarrolladores de Python usan para unir DataFrames, y comprenderla bien es la diferencia entre pasar minutos u horas en la preparación de datos.

Esta guía cubre todos los aspectos de pd.merge(): los cuatro tipos principales de joins, la combinación en múltiples columnas, el manejo de nombres duplicados y los errores comunes. Cada ejemplo usa código funcional que puede copiar directamente en su notebook.

Qué hace pd.merge()

pd.merge() combina dos DataFrames haciendo coincidir filas basándose en una o más columnas compartidas (llamadas claves). Funciona como una instrucción SQL JOIN. Usted elige en qué columnas hacer coincidir y qué tipo de join realizar, y pandas se encarga del resto.

Aquí está la sintaxis básica:

import pandas as pd
 
result = pd.merge(left, right, how='inner', on=None, left_on=None, right_on=None,
                  suffixes=('_x', '_y'), indicator=False, validate=None)

Referencia de parámetros clave

Si omite on, left_on y right_on, pandas unirá automáticamente todas las columnas que compartan el mismo nombre en ambos DataFrames.

Datos de ejemplo para todos los ejemplos

Cada ejemplo a continuación usa estos dos DataFrames:

import pandas as pd
 
employees = pd.DataFrame({
    'emp_id': [1, 2, 3, 4, 5],
    'name': ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'],
    'dept_id': [10, 20, 10, 30, 20]
})
 
departments = pd.DataFrame({
    'dept_id': [10, 20, 40],
    'dept_name': ['Engineering', 'Marketing', 'Sales']
})
 
print(employees)
print(departments)

Salida:

   emp_id     name  dept_id
0       1    Alice       10
1       2      Bob       20
2       3  Charlie       10
3       4    Diana       30
4       5      Eve       20

   dept_id    dept_name
0       10  Engineering
1       20    Marketing
2       40        Sales

Observe que dept_id 30 existe solo en employees, y dept_id 40 existe solo en departments. Esta discordancia es intencional: hace que la diferencia entre los tipos de join sea obvia.

Inner Merge (predeterminado)

Un inner merge devuelve solo las filas donde la clave existe en ambos DataFrames. Las filas sin coincidencia se eliminan.

inner_result = pd.merge(employees, departments, on='dept_id', how='inner')
print(inner_result)

Salida:

   emp_id     name  dept_id    dept_name
0       1    Alice       10  Engineering
1       3  Charlie       10  Engineering
2       2      Bob       20    Marketing
3       5      Eve       20    Marketing

Diana (dept_id=30) se elimina porque el departamento 30 no existe en la tabla departments. El departamento 40 (Ventas) también está ausente porque ningún empleado pertenece a él.

Cuándo usar inner merge: Úselo cuando solo quiera registros completos: filas que tengan datos válidos en ambos lados. Este es el predeterminado más seguro porque nunca introduce valores NaN de filas no coincidentes.

Left Merge

Un left merge mantiene todas las filas del DataFrame izquierdo y solo las filas coincidentes del derecho. Donde no hay coincidencia, las columnas del lado derecho se llenan con NaN.

left_result = pd.merge(employees, departments, on='dept_id', how='left')
print(left_result)

Salida:

   emp_id     name  dept_id    dept_name
0       1    Alice       10  Engineering
1       2      Bob       20    Marketing
2       3  Charlie       10  Engineering
3       4    Diana       30          NaN
4       5      Eve       20    Marketing

Diana ahora está incluida, pero su dept_name es NaN porque el departamento 30 no tiene entrada en la tabla departments.

Cuándo usar left merge: Úselo cuando el DataFrame izquierdo sea su conjunto de datos "primario" y quiera enriquecerlo con columnas adicionales, sin perder ninguna fila de la tabla primaria. Este es el tipo de merge más común en la práctica.

Right Merge

Un right merge es el espejo de un left merge. Mantiene todas las filas del DataFrame derecho y solo las filas coincidentes del izquierdo.

right_result = pd.merge(employees, departments, on='dept_id', how='right')
print(right_result)

Salida:

   emp_id     name  dept_id    dept_name
0     1.0    Alice       10  Engineering
1     3.0  Charlie       10  Engineering
2     2.0      Bob       20    Marketing
3     5.0      Eve       20    Marketing
4     NaN      NaN       40        Sales

El departamento de Ventas (dept_id=40) ahora aparece aunque ningún empleado pertenezca a él. Los campos de empleados son NaN para esa fila.

Cuándo usar right merge: En la práctica, los right merges son raros. Siempre puede reescribir un right merge como un left merge intercambiando el orden de los DataFrames. La mayoría de las bases de código prefieren left merges por consistencia.

Outer Merge (Full Outer Join)

Un outer merge devuelve todas las filas de ambos DataFrames. Donde no hay coincidencia, los valores faltantes se llenan con NaN.

outer_result = pd.merge(employees, departments, on='dept_id', how='outer')
print(outer_result)

Salida:

   emp_id     name  dept_id    dept_name
0     1.0    Alice       10  Engineering
1     3.0  Charlie       10  Engineering
2     2.0      Bob       20    Marketing
3     5.0      Eve       20    Marketing
4     4.0    Diana       30          NaN
5     NaN      NaN       40        Sales

Tanto Diana (sin departamento coincidente) como Ventas (sin empleados coincidentes) aparecen en el resultado.

Cuándo usar outer merge: Úselo cuando necesite una imagen completa de ambos conjuntos de datos y quiera identificar qué filas no coincidieron. El parámetro indicator es especialmente útil aquí.

Comparación rápida de tipos de merge

Combinar en múltiples columnas

Cuando una sola columna no es suficiente para identificar únicamente una coincidencia, pase una lista de nombres de columnas a on:

sales = pd.DataFrame({
    'year': [2024, 2024, 2025, 2025],
    'quarter': ['Q1', 'Q2', 'Q1', 'Q2'],
    'revenue': [100, 150, 200, 250]
})
 
targets = pd.DataFrame({
    'year': [2024, 2024, 2025, 2025],
    'quarter': ['Q1', 'Q2', 'Q1', 'Q2'],
    'target': [120, 140, 210, 230]
})
 
merged = pd.merge(sales, targets, on=['year', 'quarter'])
print(merged)

Salida:

   year quarter  revenue  target
0  2024      Q1      100     120
1  2024      Q2      150     140
2  2025      Q1      200     210
3  2025      Q2      250     230

Esto es el equivalente de una clave compuesta en SQL. Tanto year como quarter deben coincidir para que las filas se unan.

Combinar con nombres de columna diferentes

A veces los dos DataFrames usan nombres diferentes para el mismo concepto. Use left_on y right_on en lugar de on:

orders = pd.DataFrame({
    'order_id': [101, 102, 103],
    'customer_id': [1, 2, 3],
    'amount': [50.0, 75.0, 120.0]
})
 
customers = pd.DataFrame({
    'id': [1, 2, 4],
    'name': ['Alice', 'Bob', 'Diana']
})
 
merged = pd.merge(orders, customers, left_on='customer_id', right_on='id', how='left')
print(merged)

Salida:

   order_id  customer_id  amount   id   name
0       101            1    50.0  1.0  Alice
1       102            2    75.0  2.0    Bob
2       103            3   120.0  NaN    NaN

Observe que tanto las columnas customer_id como id aparecen en el resultado. Puede eliminar el duplicado después:

merged = merged.drop(columns=['id'])

Manejo de nombres de columnas duplicadas con sufijos

Cuando ambos DataFrames tienen columnas con el mismo nombre (además de la clave), pandas agrega sufijos para distinguirlas:

df1 = pd.DataFrame({
    'id': [1, 2, 3],
    'score': [85, 90, 78]
})
 
df2 = pd.DataFrame({
    'id': [1, 2, 3],
    'score': [88, 92, 80]
})
 
# Sufijos predeterminados
merged = pd.merge(df1, df2, on='id')
print(merged)

Salida:

   id  score_x  score_y
0   1       85       88
1   2       90       92
2   3       78       80

Puede personalizar los sufijos para hacer los nombres de columnas más significativos:

merged = pd.merge(df1, df2, on='id', suffixes=('_midterm', '_final'))
print(merged)

Salida:

   id  score_midterm  score_final
0   1             85           88
1   2             90           92
2   3             78           80

Uso del parámetro indicator

El parámetro indicator agrega una columna _merge que le dice de dónde vino cada fila:

result = pd.merge(employees, departments, on='dept_id', how='outer', indicator=True)
print(result)

Salida:

   emp_id     name  dept_id    dept_name      _merge
0     1.0    Alice       10  Engineering        both
1     3.0  Charlie       10  Engineering        both
2     2.0      Bob       20    Marketing        both
3     5.0      Eve       20    Marketing        both
4     4.0    Diana       30          NaN   left_only
5     NaN      NaN       40        Sales  right_only

Esto es extremadamente útil para verificaciones de calidad de datos: puede filtrar rápidamente las filas que no coincidieron:

unmatched = result[result['_merge'] != 'both']
print(unmatched)

merge() vs join() vs concat() -- Cuándo usar cada uno

Pandas ofrece tres formas de combinar DataFrames. Aquí está cuándo usar cada uno:

Regla general:

• Use pd.merge() cuando esté combinando DataFrames basándose en valores de columnas (el caso más común).
• Use df.join() cuando su clave de join sea el índice y quiera una sintaxis más corta.
• Use pd.concat() cuando esté apilando DataFrames uno encima del otro (agregando filas) o uno al lado del otro.

Errores comunes y solución de problemas

1. MergeError: las columnas se superponen pero no se especificó sufijo

Esto sucede cuando ambos DataFrames tienen columnas no clave con el mismo nombre y establece suffixes=(False, False):

# Solución: use sufijos significativos
merged = pd.merge(df1, df2, on='id', suffixes=('_left', '_right'))

2. Explosión inesperada de filas (merge muchos a muchos)

Si ambos DataFrames tienen valores duplicados en la clave de join, pandas crea un producto cartesiano de las filas coincidentes. Esto puede hacer que su resultado tenga muchas más filas que cualquiera de las entradas:

# Verificar duplicados antes de combinar
print(df1['key'].duplicated().sum())
print(df2['key'].duplicated().sum())
 
# Use validate para detectar esto temprano
merged = pd.merge(df1, df2, on='key', validate='one_to_many')

El parámetro validate acepta 'one_to_one', 'one_to_many', 'many_to_one' y 'many_to_many'. Lanza un MergeError si los datos no coinciden con la cardinalidad esperada.

3. La columna clave tiene dtypes diferentes

Si un DataFrame almacena la clave como int64 y el otro como object (cadena), el merge fallará o producirá cero coincidencias:

# Verificar dtypes
print(df1['id'].dtype)  # int64
print(df2['id'].dtype)  # object
 
# Solución: convertir al mismo tipo
df2['id'] = df2['id'].astype(int)
merged = pd.merge(df1, df2, on='id')

4. Valores NaN en las claves

Las filas con NaN en la columna de clave de join no coincidirán con nada (NaN != NaN en pandas). Elimínelas o rellénelas primero:

df1 = df1.dropna(subset=['key'])

Visualice sus DataFrames combinados con PyGWalker

Después de combinar sus datos, el siguiente paso suele ser explorar el resultado: observar distribuciones, detectar patrones y verificar anomalías. En lugar de escribir docenas de llamadas a matplotlib o seaborn, puede usar PyGWalker (opens in a new tab), una biblioteca de Python de código abierto que convierte cualquier DataFrame de pandas en una interfaz de exploración visual interactiva similar a Tableau directamente dentro de Jupyter Notebook.

import pandas as pd
import pygwalker as pyg
 
# Combine sus DataFrames
employees = pd.DataFrame({
    'emp_id': [1, 2, 3, 4, 5],
    'name': ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'],
    'dept_id': [10, 20, 10, 30, 20],
    'salary': [95000, 82000, 105000, 78000, 91000]
})
 
departments = pd.DataFrame({
    'dept_id': [10, 20, 30],
    'dept_name': ['Engineering', 'Marketing', 'Design']
})
 
merged = pd.merge(employees, departments, on='dept_id')
 
# Lance visualización interactiva: arrastre y suelte para explorar
walker = pyg.walk(merged)

Con PyGWalker, puede arrastrar dept_name al eje x y salary al eje y para ver instantáneamente la distribución de salarios por departamento, sin necesidad de código de gráficos. Puede crear gráficos de barras, gráficos de dispersión, histogramas y más simplemente arrastrando campos. Es especialmente potente para explorar los resultados de merges complejos donde necesita verificar que el join funcionó como se esperaba.

Puede probar PyGWalker ahora mismo en Google Colab (opens in a new tab), Kaggle (opens in a new tab), o instalarlo con pip install pygwalker.

FAQ

¿Cuál es la diferencia entre pandas merge y join?

pd.merge() une DataFrames basándose en valores de columnas por defecto y admite todos los tipos de join (inner, left, right, outer, cross). df.join() une en el índice por defecto y usa un left join. Bajo el capó, join() llama a merge(), por lo que producen los mismos resultados: merge() simplemente le da más control sobre qué columnas hacer coincidir.

¿Cómo combino dos DataFrames en múltiples columnas en pandas?

Pase una lista de nombres de columnas al parámetro on: pd.merge(df1, df2, on=['col_a', 'col_b']). Ambas columnas deben coincidir para que las filas se unan. Esto es equivalente a una clave compuesta en SQL.

¿Por qué mi pandas merge crea filas duplicadas?

Las filas duplicadas aparecen cuando la clave de join tiene valores repetidos en uno o ambos DataFrames. Pandas crea un producto cartesiano de todas las filas coincidentes. Use df.duplicated(subset=['key']).sum() para verificar duplicados antes de combinar, o use validate='one_to_one' para detectarlo temprano.

¿Qué es un cross merge en pandas?

Un cross merge (how='cross') produce el producto cartesiano de ambos DataFrames: cada fila de la izquierda se empareja con cada fila de la derecha. Si la izquierda tiene 3 filas y la derecha tiene 4 filas, el resultado tiene 12 filas. Es útil para generar todas las combinaciones posibles, como emparejar cada producto con cada ubicación de tienda.

¿Cómo realizo un pandas merge en el índice?

Establezca left_index=True y/o right_index=True: pd.merge(df1, df2, left_index=True, right_index=True). También puede mezclar claves de índice y columna: pd.merge(df1, df2, left_on='col_a', right_index=True).

Conclusión

La función merge() de pandas es la herramienta más flexible y ampliamente utilizada para combinar DataFrames en Python. Para recapitular los puntos clave:

• Inner merge (predeterminado) mantiene solo las filas que coinciden en ambos DataFrames.
• Left merge mantiene todas las filas del DataFrame izquierdo, llenando NaN donde la derecha no tiene coincidencia.
• Right merge mantiene todas las filas del DataFrame derecho, pero prefiera left merge con orden intercambiado para consistencia.
• Outer merge mantiene todo de ambos lados, útil para identificar registros no coincidentes con indicator=True.
• Use on para claves del mismo nombre, left_on/right_on para claves de nombres diferentes y suffixes para manejar columnas superpuestas.
• Siempre verifique claves duplicadas y dtypes no coincidentes antes de combinar para evitar resultados inesperados.

Una vez que sus datos están combinados, herramientas como PyGWalker (opens in a new tab) le permiten explorar visualmente el resultado sin escribir código de gráficos, haciendo que todo el flujo de trabajo de análisis sea más rápido e intuitivo.