df.to _dict(orient='records') 是 Pandas DataFrame 的一个方法，用于将数据转换为字典列表格式。以下是详细解释及实例说明：

一、核心含义

1. 作用
   将 DataFrame 的每一行转换为一个字典，所有字典组成一个列表。
   每个字典的键（key）是 DataFrame 的列名，值（value）是该行对应列的数据。
   证据来源：

2. 参数 orient='records'

   • orient 指定输出字典的格式：
     • 'records' 生成列表（每个元素为行字典）
     • 其他选项如 'dict'（列名→列值字典）、'index'（行索引→行值字典）等（详见 ）
   • 注意：Pandas 1.1.x 后弃用短参数名（如 'records'），推荐完整写法 orient='records' 。

---

二、实例说明

示例 1：基础转换

import pandas as pd# 创建示例 DataFrame
df = pd.DataFrame({'Name': ['Alice', 'Bob'],'Age': [30, 28],'City': ['Beijing', 'Shanghai']
})# 使用 orient='records'
records = df.to_dict(orient='records')
print(records)

输出：

[{'Name': 'Alice', 'Age': 30, 'City': 'Beijing'},{'Name': 'Bob', 'Age': 28, 'City': 'Shanghai'}
]

每行数据转换为独立字典，键为列名（Name, Age, City）。

---

示例 2：特殊场景处理

1. 列名为数字字符串时
   若列名是整数格式的字符串（如 '0'），旧版本 Pandas（如 0.24.0）会自动添加下划线（{'_0': value}）：

   df_bad = pd.DataFrame({str(i): [i] for i in range(3)})  # 列名为 ['0','1','2']
   print(df_bad.to_dict('records'))  # 输出 [{'_0': 0, '_1': 1, '_2': 2}]
   

2. 空 DataFrame 时
   无数据的 DataFrame 返回空列表 []，而非预期的 [{}, {}, ...]（行为可能因版本而异）：

   empty_df = pd.DataFrame([{}, {}]) 
   print(empty_df.to_dict(orient='records'))  # 输出 []
   

3. 性能对比
   大数据集下原生方法可能比自定义实现慢（如 500 万行数据慢 3 倍），因需类型检查和装箱操作 。

---

三、典型应用场景

1. 数据序列化
   转换为字典列表后可直接用于 JSON 序列化，方便 API 传输或存储 ：

   import json
   json_data = json.dumps(df.to_dict(orient='records'))
   

2. 机器学习特征处理
   配合 sklearn.feature_extraction.DictVectorizer 对分类特征做 One-Hot 编码 ：

   from sklearn.feature_extraction import DictVectorizer
   vec = DictVectorizer(sparse=False)
   X = vec.fit_transform(df.to_dict(orient='records'))
   

3. 数据遍历
   直接迭代每行数据，代码更简洁 ：

   for record in df.to_dict(orient='records'):print(record['Name'], record['Age'])
   

---

四、注意事项

1. 版本兼容性

   • Pandas ≥1.1.x 需用 orient='records' 而非简写 'records'，否则触发弃用警告 。
   • 列数 ≥255 时，旧版本（0.24.0）可能报错 AttributeError，建议升级 Pandas 。

2. 数据类型保留
   默认保留 Pandas 内部类型（如 Timestamp），若需原生 Python 类型（如 datetime），需提前转换：

   df['date'] = df['date'].astype(object)  # 将时间戳转为 Python datetime
   records = df.to_dict(orient='records')
   

   *否则输出可能包含非标准类型（如 Timestamp）导致序列化失败 *。

3. 索引处理
   orient='records' 默认忽略行索引（index）。若需包含索引，应先重置索引：

   df.reset_index(inplace=True)  # 添加索引列
   records = df.to_dict(orient='records')
   

---

总结

df.to _dict(orient='records') 的核心功能是将 DataFrame 按行转换为字典列表，每个字典代表一行数据，键为列名。它适用于数据序列化、机器学习特征工程和简化数据遍历，但需注意版本差异、列名格式和数据类型转换问题。