---
title: "dataframe-merge (en)"
description: pandas merge() combines DataFrames on a shared column or index — 7 examples.
url: "https://aaronchan.com/kb/dataframe-merge/"
updated: "2026-09-15"
category: "Code-Python (en)"
tags:
  - python
---

# dataframe-merge (en)

pandas `merge()` combines two DataFrames on a shared column or index. These 7 examples cover inner / left / outer joins, different key names, multiple keys, and merging by index.

## Example 1: Inner merge — the default, keeps only matching keys

 Copy

```
import pandas as pd
students = pd.DataFrame({
    "id": [1,2,3],
    "Name":["Alice", "Bob", "Cat"]
})

scores = pd.DataFrame({
    "id":[1, 2, 4],
    "Score": [80,90,70]
})

pd.merge(students, scores, on="id", how="inner")
```

**output:**

```
	id	Name	Score
0	1	Alice	80
1	2	Bob	90
```

---

## Example 2: Left merge — keep all rows from the left, fill missing with NaN

 Copy

```
import pandas as pd
students = pd.DataFrame({
    "id": [1,2,3],
    "Name":["Alice", "Bob", "Cat"]
})

scores = pd.DataFrame({
    "id":[1, 2, 4],
    "Score": [80,90,70]
})

# pd.merge(students, scores, on="id", how="inner")
pd.merge(students, scores, on="id", how="left")
```

**output:**

```
	id	Name	Score
0	1	Alice	80.0
1	2	Bob	90.0
2	3	Cat	NaN
```

---

## Example 3: Outer merge — keep all rows from both sides

 Copy

```
import pandas as pd
students = pd.DataFrame({
    "id": [1,2,3],
    "Name":["Alice", "Bob", "Cat"]
})

scores = pd.DataFrame({
    "id":[1, 2, 4],
    "Score": [80,90,70]
})

# pd.merge(students, scores, on="id", how="inner")
pd.merge(students, scores, on="id", how="outer")
```

**output:**

```
	id	Name	Score
0	1	Alice	80.0
1	2	Bob	90.0
2	3	Cat	NaN
3	4	NaN	70.0
```

---

## Example 4: Merge with different column names — left_on / right_on

 Copy

```
#join with different keys
import pandas as pd

#Student table
students = pd.DataFrame({
    "id" : [1,2,3],
    "name": ["Alice", "Bob", "Cat"]
})

#Score table
score = pd.DataFrame({
    "student_id" : [2,3,4],
    "score" : [90,75, 88]
})

pd.merge(
    students,
    score,
    left_on="id",
    right_on="student_id",
    how="left"
)
```

**output:**

```
	id	name	student_id	score
0	1	Alice	NaN	NaN
1	2	Bob	2.0	90.0
2	3	Cat	3.0	75.0
```

---

## Example 5: Merge on multiple keys — on=["id", "date"]

 Copy

```
#Merge with multi keys
import pandas as pd

dfA = pd.DataFrame({
    "id": [1, 1, 2, 3],
    "date": ["2025-01-01", "2025-01-02", "2025-01-01", "2025-01-01"],
    "amount": [100, 150, 200, 250]
})

dfB = pd.DataFrame({
    "id": [1, 2, 2, 3],
    "date": ["2025-01-01", "2025-01-01", "2025-01-03", "2025-01-01"],
    "status": ["Paid", "Pending", "Paid", "Refunded"]
})

print(dfA, 'n')
print(dfB, 'n')

merged_df = pd.merge(
    dfA, dfB,
    on=["id", "date"],
    how="outer"
)

print(merged_df)
```

**output:**

```
   id        date  amount
0   1  2025-01-01     100
1   1  2025-01-02     150
2   2  2025-01-01     200
3   3  2025-01-01     250

   id        date    status
0   1  2025-01-01      Paid
1   2  2025-01-01   Pending
2   2  2025-01-03      Paid
3   3  2025-01-01  Refunded

   id        date  amount    status
0   1  2025-01-01   100.0      Paid
1   1  2025-01-02   150.0       NaN
2   2  2025-01-01   200.0   Pending
3   2  2025-01-03     NaN      Paid
4   3  2025-01-01   250.0  Refunded
```

---

## Example 6: Merge by index — left_index / right_index

 Copy

```
#Merge by index
import pandas as pd

df1 = pd.DataFrame({
    "Age": [25,30,22]
}, index=["Alice", "Bob",  "Cat"])

df2 = pd.DataFrame({
    "City": ["HK", "Tokyo", "Sydney", "Taiwan"]
}, index=["Alice", "Bob",  "Cat", "David"])

merged = pd.merge(
    df1,
    df2,
    left_index=True,
    right_index=True,
    how='inner'
)
print(merged)
```

**output:**

```
       Age    City
Alice   25      HK
Bob     30   Tokyo
Cat     22  Sydney
```

---

## Example 7: Merge a column with an index — left_on + right_index

 Copy

```
#Merge by index
import pandas as pd

df1 = pd.DataFrame ({
    "customer_id": [101,102,103],
    "order": ["A", "B", "C"]
})

df2 = pd.DataFrame ({
    "name": ["Alice", "Bob",  "Cat"],
    "city": ["HK", "Tokyo", "Sydney"]
}, index=[101,102,103])

result = pd.merge(
    df1,
    df2,
    left_on="customer_id",
    right_index=True
)

print (result)
```

**output:**

```
   customer_id order   name    city
0          101     A  Alice      HK
1          102     B    Bob   Tokyo
2          103     C    Cat  Sydney
```