本文详解 Pandas merge 报错“non-unique labels”的根本原因——错误地将单层列名传入嵌套列表，导致 DataFrame 创建出意外的 MultiIndex 列结构，进而使 on 参数无法正确识别合并键。
本文详解 pandas `merge` 报错“non-unique labels”的根本原因——错误地将单层列名传入嵌套列表，导致 dataframe 创建出意外的 multiindex 列结构，进而使 `on` 参数无法正确识别合并键。
在使用 pd.DataFrame() 构造数据时，列名参数 columns 必须是一个一维列表（如 ['date', 'symbol', 'value']），而非嵌套列表（如 [['date', 'symbol', 'value']]）。原代码中：
df1 = pd.DataFrame(data1[1:], columns=data1[:1]) # ❌ 错误！data1[:1] 是 [['date','symbol','value']]
data1[:1] 返回的是一个包含单个子列表的列表，即 [ ['date', 'symbol', 'value'] ] —— 这会触发 Pandas 的隐式 MultiIndex 列推断机制。Pandas 将其解释为具有 1 级（level-0）的 MultiIndex 列，且该级下只有一个元组标签 ('date', 'symbol', 'value')。此时，df1.columns 实际类型为 pd.MultiIndex，而 df1.columns.tolist() 显示为 [('date', 'symbol', 'value')]。
当执行 df1.merge(df2, on=['date', 'symbol']) 时，merge 尝试在列索引中查找名为 'date' 的标量标签，但当前列是 MultiIndex，不存在单层 'date' 标签（只有元组 ('date','symbol','value')），因此抛出明确提示：
ValueError: The column label 'date' is not unique. For a multi-index, the label must be a tuple with elements corresponding to each level.
⚠️ 注意：此错误与“数据中 date+symbol 是否唯一”完全无关，而是列结构定义错误引发的元数据层面问题。
✅ 正确做法是显式解包列名：
import pandas as pd
data1 = [['date', 'symbol', 'value'],
['1999-01-10', 'AAA', 101],
['1999-01-11', 'AAA', 201]]
data2 = [['date', 'symbol', 'value'],
['1999-01-10', 'BBB', 101],
['1999-01-11', 'BBB', 201]]
# ✅ 正确：用 data1[0]（一维列表）作为 columns
df1 = pd.DataFrame(data1[1:], columns=data1[0])
df2 = pd.DataFrame(data2[1:], columns=data2[0])
# 合并成功，自动后缀区分重名列（value → value_x / value_y）
result = df1.merge(df2, on=['date', 'symbol'], how='outer')
print(result)
输出：
date symbol value_x value_y 0 1999-01-10 AAA 101.0 NaN 1 1999-01-11 AAA 201.0 NaN 2 1999-01-10 BBB NaN 101.0 3 1999-01-11 BBB NaN 201.0
? 关键检查技巧：
合并前务必验证列结构：
print("df1.columns:", df1.columns)
print("type(df1.columns):", type(df1.columns))
# 若输出 <class>，说明列定义有误</class>
? 总结：Pandas merge 对列索引的严格性要求开发者清晰区分「数据内容唯一性」与「列元数据结构正确性」。避免嵌套传参、善用 df.columns 调试，即可快速规避此类看似神秘的报错。
