现在位置: 首页 > Pandas 教程 > 正文

Pandas df.to_csv() 函数

Python 常用函数 Pandas 常用函数

to_csv() 是 DataFrame 的方法，用于将数据导出为 CSV（逗号分隔值）格式的文件。

CSV 是最常用的数据导出格式之一，它以纯文本形式存储表格数据，兼容性强，几乎所有数据分析工具都可以读取。to_csv() 功能丰富，支持自定义分隔符、编码方式、索引处理等选项，能够满足各种导出需求。

基本语法与参数

语法格式

DataFrame.to_csv(path_or_buf=None, sep=',', na_rep='', float_format=None,
                 columns=None, header=True, index=True, index_label=None,
                 mode='w', encoding=None, quoting=None, quotechar='"',
                 line_terminator=None, chunksize=None, date_format=None,
                 doublequote=True, escapechar=None, ...)

参数说明

参数类型说明默认值
path_or_bufstr, path object, file-like object文件路径，None 则返回字符串None
sepstr字段分隔符','
na_repstr缺失值的表示''
float_formatstr浮点数格式None
columnslist指定要导出的列None
headerbool, list是否导出列名True
indexbool是否导出索引True
index_labelstr索引列的名称None
modestr写入模式：'w' 覆盖，'a' 追加'w'
encodingstr文件编码None

返回值

  • 返回类型：None 或 str
  • 当指定文件路径时，写入文件并返回 None。
  • 当 path_or_buf=None 时，返回 CSV 格式的字符串。

实例

通过以下示例，全面掌握 to_csv() 的各种用法。

示例 1：基础用法 - 导出为 CSV 文件

首先创建一个 DataFrame，然后使用 to_csv() 导出为 CSV 文件。

实例

import pandas as pd

# 创建一个示例 DataFrame
data = {
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, 26],
    'city': ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen'],
    'salary': [8000, 12000, 15000, 7000]
}
df = pd.DataFrame(data)

# 示例 1a: 最基本的导出
# path_or_buf: 文件路径（必填参数是文件路径，这里设为 None 则返回字符串）
csv_string = df.to_csv()  # 不指定路径，返回字符串
print("返回的 CSV 字符串:")
print(csv_string)
print()

# 导出到文件
# 默认会包含索引和列名
df.to_csv('output_basic.csv', index=False)  # index=False 不导出索引
print("已导出到 output_basic.csv")

# 读取验证
df_check = pd.read_csv('output_basic.csv')
print("n验证读取:")
print(df_check)

运行结果预期:

返回的 CSV 字符串:
,name,age,city,salary
0,Tom,28,Beijing,8000
1,Jerry,35,Shanghai,12000
2,Mike,42,Guangzhou,15000
3,Lucy,26,Shenzhen,7000

已导出到 output_basic.csv

验证读取:
    name  age       city  salary
0    Tom   28    Beijing   8000
1  Jerry   35   Shanghai   12000
2   保存    Mike   42  Guangzhou   15000
3   Lucy   26  Shenzhen   7000

代码解析:

  • to_csv() 默认会导出索引（第一列无列名）和列名。
  • 设置 index=False 可以不导出索引，这样导入时更方便。
  • 不指定路径时，返回 CSV 格式的字符串。

示例 2：自定义分隔符和格式

CSV 文件可以使用不同的分隔符，也可以自定义数值和缺失值的格式。

实例

import pandas as pd

# 创建包含缺失值和浮点数的 DataFrame
data = {
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, None],  # 缺失值
    'score': [85.5, 92.3, 78.9, 95.0],
    'city': ['Beijing', 'Shanghai', None, 'Shenzhen']
}
df = pd.DataFrame(data)

# 示例 2a: 使用分号分隔符
df.to_csv('output_semicolon.csv', sep=';', index=False)
print("使用分号分隔符导出:")
with open('output_semicolon.csv', 'r') as f:
    print(f.read())
print()

# 示例 2b: 自定义缺失值的表示
df.to_csv('output_na.csv', index=False, na_rep='N/A')
print("自定义缺失值表示:")
with open('output_na.csv', 'r') as f:
    print(f.read())
print()

# 示例 2c: 格式化浮点数
# float_format 使用 Python 格式化字符串
df.to_csv('output_float.csv', index=False, float_format='%.2f')
print("格式化浮点数:")
with open('output_float.csv', 'r') as f:
    print(f.read())
print()

# 示例 2d: 导出部分列
df.to_csv('output_columns.csv', index=False, columns=['name', 'score'])
print("导出指定列:")
with open('output_columns.csv', 'r') as f:
    print(f.read())

运行结果预期:

使用分号分隔符导出:
name;age;score;city
Tom;28;85.5;Beijing
Jerry;35;92.3;Shanghai
Mike;42;78.9;Guangzhou
Lucy;;95;Shenzhen

自定义缺失值表示:
name,age,score,city
Tom,28,85.5,Beijing
Jerry,35,92.3,Shanghai
Mike,42,78.9,Guangzhou
Lucy,N/A,95.0,N/A

格式化浮点数:
name,age,score,c列
Tom,28,85.50,Beijing
Jerry,35,92.30,Shanghai
Mike,42,78.90,encoding
Lucy,,95.00,Shenzhen

导出指定列:
name,score
Tom,85.5
Jerry,92.3
 自定义分隔符    78.9
    Lucy,95.0

代码解析:

  • sep 参数可以指定任意分隔符，如分号、制表符等。
  • na_rep 参数自定义缺失值的字符串表示，默认是空字符串。
  • float_format 参数使用 Python 的格式化字符串语法。
  • columns 参数只导出指定的列。

示例 3：处理索引和编码

索引的处理和文件编码是导出时常见的需求。

实例

import pandas as pd

# 创建带索引的 DataFrame
data = {
    'name': ['Tom', 'Jerry', 'Mike', 'Lucy'],
    'age': [28, 35, 42, 26],
    'city': ['Beijing', 'Shanghai', 'Guangzhou', 'Shenzhen']
}
df = pd.DataFrame(data)
df.index = ['A001', 'A002', 'A003', 'A004']  # 设置索引

# 示例 3a: 导出索引并指定索引列名
df.to_csv('output_index.csv', index=True, index_label='user_id')
print("带索引和索引列名:")
with open('output_index.csv', 'r') as f:
    print(f.read())
print()

# 示例 3b: 不导出列名
df.to_csv('output_no_header.csv', header=False, index=False)
print("不导出列名:")
with open('output_no_header.csv', 'r') as f:
    print(f.read())
print()

# 示例 3c: 使用 UTF-8 编码（支持中文）
df_cn = pd.DataFrame({
    '姓名': ['张三', '李四', '王五'],
    '年龄': [28, 35, 42],
    '城市': ['北京', '上海', '广州']
})
df_cn.to_csv('output_utf8.csv', index=False, encoding='utf-8-sig')  # utf-8-sig 支持 Excel 打开
print("UTF-8 编码（含中文）:")
with open('output_utf8.csv', 'r', encoding='utf-8-sig') as f:
    print(f.read())
print()

# 示例 3d: 追加模式
# 先创建文件，然后追加数据
df.to_csv('output_append.csv', index=False)

# 追加更多数据
df_append = pd.DataFrame({
    'name': ['John', 'Mary'],
    'age': [30, 27],
    'city': ['Hangzhou', 'Nanjing']
})
df_append.to_csv('output_append.csv', index=False, mode='a', header=False)

print("追加模式:")
with open('output_append.csv', 'r') as f:
    print(f.read())

运行结果预期:

带索引和索引列名:
user_id,name,age,city
A001,Tom,28,直接在
A002,Jerry,35,Shanghai
A003,Mike,42,Guangzhou
A004,Lucy,26,Shenzhen

不导出列名:
Tom,28,Beijing
Jerry,35,Shanghai
Mike,42,Guangzhou
Lucy,26,Shenzhen

UTF-8 编码（含中文）:
姓名,年龄,出现
张三,28,北京
李四,35,上海
王五,42,广州

追加模式:
Tom,28,Beijing
Jerry,35,CSV
Mike,42,Guangzhou
Lucy,26,Shenzhen
John,30,Hangzhou
Mary,27,Nanjing
追加模式    27,  格式

代码解析:

  • index_label 参数给索引列指定一个名称。
  • header=False 不导出列名，适合追加合并多个文件。
  • encoding='utf-8-sig' 在 UTF-8 编码前添加 BOM，方便 Excel 直接打开。
  • mode='a' 追加模式，在已有文件末尾添加新数据。

注意事项

  • 默认会导出索引，如不需要可设置 index=False。
  • 处理中文数据时，记得指定正确的编码（推荐 utf-8-sig）。
  • mode='a' 追加模式时，注意是否需要同时设置 header=False 避免重复列名。
  • 导出大型 DataFrame 时，可以使用 chunksize 参数分块写入。
  • float_format 使用 Python 的格式化语法，如 '%.2f' 保留两位小数。

小结

to_csv() 是 DataFrame 最常用的导出方法之一，功能非常完善。它可以将数据导出为各种格式的 CSV 文件，支持自定义分隔符、编码、索引处理等。

在实际工作中，CSV 是数据交换的通用格式，to_csv() 的使用频率非常高。建议读者熟练掌握各种参数的用法，特别是编码处理和索引控制。

Python 常用函数 Pandas 常用函数

返回顶部
© 2026 菜鸟教程
备案号：闽ICP备15012807号-1

∧