23.6 文本格式导出

核心内容

将 DataFrame 导出为 CSV、JSON、HTML、LaTeX、Markdown、XML 等文本格式。

一、to_csv() — 导出 CSV

最常用的导出方式，通用性最强。

import pandas as pd
import numpy as np
 
df = pd.DataFrame({
    'id': [1, 2, 3],
    'name': ['Alice', 'Bob', 'Charlie'],
    'score': [95.5, 88.0, 76.25]
})
 
# 基础导出
df.to_csv('output.csv')
 
# 常用参数组合
df.to_csv(
    'output.csv',
    sep=',',                 # 分隔符
    na_rep='NULL',           # 缺失值表示
    float_format='%.2f',     # 浮点格式
    columns=['id', 'name'],  # 选择列
    header=True,             # 是否写列名
    index=False,             # 是否写行索引
    index_label='id',        # 索引列名
    encoding='utf-8-sig',    # 编码（Excel 兼容）
    mode='w',                # 'w' 覆盖 / 'a' 追加
    compression='gzip',      # 压缩
    date_format='%Y-%m-%d',  # 日期格式
    quoting=1,               # QUOTE_ALL
    quotechar='"',           # 引号字符
    escapechar='\\',         # 转义符
    decimal='.',             # 小数点
    line_terminator='\n',    # 行终止符
    chunksize=10000,         # 分块写入
    errors='strict'          # 编码错误处理
)
 
# 不写索引直接追加
df.to_csv('output.csv', index=False, mode='a', header=False)

参数	说明
sep	字段分隔符（默认 ,）
na_rep	缺失值字符串表示
float_format	浮点格式字符串
columns	导出列子集
header	是否写列名（可传字符串列表自定义）
index	是否写行索引
index_label	索引列名
mode	’w’ 覆盖、‘a’ 追加
encoding	编码（中文推荐 utf-8-sig）
compression	压缩方式
quoting	引用规则（csv.QUOTE_*）
date_format	日期时间格式
chunksize	每次写入行数

二、to_json() — 导出 JSON

# 默认格式
df.to_json('data.json')
 
# orient 方向选择
df.to_json('orient_records.json', orient='records')    # [{...},{...}]
df.to_json('orient_split.json',   orient='split')      # {"columns":[...],"index":[...],"data":[...]}
df.to_json('orient_index.json',   orient='index')      # {"0":{...},"1":{...}}
df.to_json('orient_columns.json', orient='columns')    # {"col":{...}}
df.to_json('orient_values.json',  orient='values')     # [[...],[...]]
df.to_json('orient_table.json',   orient='table')      # {"schema":...,"data":...}
 
# 常用参数
df.to_json(
    'data.json',
    orient='records',
    date_format='iso',          # 'iso' ISO8601 / 'epoch' 时间戳
    double_precision=10,        # 浮点精度
    force_ascii=False,          # 是否强制 ASCII（中文需 False）
    date_unit='ms',             # 时间戳单位：s / ms / us / ns
    default_handler=str,        # 未知类型处理
    lines=True,                 # JSON Lines（每行一个对象）
    compression='gzip',
    index=False,                # orient 包含索引时是否写
    indent=2                    # 缩进美化
)

orient	结构	适用场景
records	数组对象	最常用，API 对接
split	分离 schema / data	pandas 原生还原
index	以索引为键	层级数据
columns	以列为键	列优先数据
values	纯数组	最省空间
table	含 schema	完整元数据

三、to_html() — 导出 HTML

# 基础导出
df.to_html('table.html')
 
# 常用参数
df.to_html(
    'table.html',
    buf='table.html',
    columns=['name', 'score'],
    col_space=100,             # 列宽
    header=True,
    index=True,
    na_rep='N/A',
    formatters={'score': lambda x: f'{x:.1f}'},   # 格式化函数
    float_format='%.2f',
    sparsify=True,             # 多级索引合并显示
    index_names=True,
    justify='center',          # 列标题对齐
    border=1,                  # table border
    classes='dataframe',       # CSS 类名
    escape=True,               # HTML 转义
    max_rows=100,
    max_cols=20,
    show_dimensions=True,
    table_id='my_table',
    render_links=True          # URL 自动转链接
)

四、to_latex() — 导出 LaTeX

# 基础导出
df.to_latex('table.tex')
 
# 常用参数
df.to_latex(
    'table.tex',
    buf='table.tex',
    columns=['name', 'score'],
    header=True,
    index=True,
    na_rep='-',
    formatters={'score': '{:.2f}'.format},
    float_format='%.2f',
    sparsify=True,              # 多级索引合并
    index_names=True,
    bold_rows=True,             # 行索引加粗
    column_format='lc',         # 列对齐格式
    longtable=False,            # 跨页表格
    escape=True,                # 特殊字符转义
    encoding='utf-8',
    multicolumn=True,
    multirow=True,
    caption='表1：测试数据',
    label='tab:data',
    position='H',
    hrules=True                 # booktabs 横线
)

五、to_markdown() — 导出 Markdown

# 导出为 Markdown 表格
md_str = df.to_markdown()
print(md_str)
# |    | id | name   | score |
# |---:|----:|:-------|------:|
# |  0 |  1 | Alice  | 95.5  |
# |  1 |  2 | Bob    | 88    |
# |  2 |  3 | Charlie| 76.25 |
 
# 写入文件
df.to_markdown('table.md')
 
# 参数
df.to_markdown(
    buf='table.md',
    mode='w',               # 'a' 追加
    index=True,             # 是否包含索引
    tablefmt='pipe',        # 'pipe' / 'github' / 'grid' / 'html' / 'latex' 等
    headers=['编号', '姓名', '分数'],   # 自定义表头
    showindex=True,
    floatfmt='.2f',         # 浮点格式
    intfmt=',d',            # 整数格式
    stralign='left',
    disable_numparse=False
)

tablefmt 常用值

'pipe'（GitHub 风格）、'grid'（ASCII 网格）、'html'、'latex'、'simple'、'rst'。

六、to_xml() — 导出 XML

# 基础导出
df.to_xml('data.xml')
 
# 常用参数
df.to_xml(
    'data.xml',
    path_or_buffer='data.xml',
    index=False,               # 是否包含索引
    root_name='data',          # 根节点名
    row_name='record',         # 行节点名
    na_rep='',                 # 缺失值表示
    attr_cols=['id'],          # 作为属性的列
    elem_cols=['name', 'score'],  # 作为元素的列
    namespaces={'prefix': 'http://example.com'},  # 命名空间
    prefix=None,
    encoding='utf-8',
    xml_declaration=True,      # 是否包含 XML 声明
    pretty_print=True,         # 美化缩进
    parser='lxml',             # 'lxml' / 'etree'
    stylesheet='style.xsl'     # XSL 样式表
)

输出示例

<?xml version="1.0" encoding="utf-8"?>
<data>
  <record id="1">
    <name>Alice</name>
    <score>95.5</score>
  </record>
  <record id="2">
    <name>Bob</name>
    <score>88.0</score>
  </record>
</data>

文本格式对比

格式	文件大小	读写速度	保留 dtype	互操作性
CSV	大	慢	否	极强
JSON	大	慢	部分	强（Web）
HTML	大	中	否	网页展示
LaTeX	小	中	否	学术写作
Markdown	小	快	否	README / 文档
XML	大	慢	否	企业系统

相关笔记

• 23.3 格式参数与高级功能 - compression 等通用参数
• Pandas-四-数据输入输出 - 对应读取函数