HOWTO · Pandas

Pandas 追加数据到 CSV 中

本教程演示了如何在追加模式下使用 to_csv()向现有的 CSV 文件添加数据。

本页内容

使用 Pandas 的 to_csv() 和 mode="a",将 DataFrame 的行追加到 CSV 文件现有行之后。追加模式会保留文件已有内容。如果文件已有表头,请设置 header=False;如果不希望将 DataFrame 索引写成额外的 CSV 列,请设置 index=False。

将 DataFrame 追加到现有 CSV 文件

此示例先创建一个 CSV 文件,再向其中追加第二个 DataFrame。在自己的代码中,请使用 CSV 文件的实际路径。追加的列必须与现有 CSV 列的顺序一致:CSV 文件不存储可按列名自动重新排列值的架构。

运行以下示例。代码中的列名和示例数据值保留英文:

本节中的代码以及显示的标签或输出仍为英文。

from pathlib import Path
from tempfile import TemporaryDirectory

import pandas as pd

with TemporaryDirectory() as directory:
    path = Path(directory) / "records.csv"
    original = pd.DataFrame({"name": ["Ava"], "score": [8]})
    added = pd.DataFrame({"name": ["Noah"], "score": [9]})

    original.to_csv(path, index=False)
    added.to_csv(path, mode="a", header=False, index=False)
    print(path.read_text(), end="")

第一次写入会创建文件及其表头。第二次写入使用 mode="a" 在文件末尾添加一行,并设置 header=False 以避免重复写入列名,设置 index=False 以避免 Pandas 写入行索引。最终文件会先包含原有行,再包含追加的行。如果要将 DataFrame 索引作为一列写入,请省略 index=False,并在读取 CSV 时一并处理这列。

仅在 CSV 文件为空时写入表头

如果目标文件可能为空或尚不存在,可以用追加模式打开文件,并检查当前文件位置。使用 mode="a" 打开不存在的路径时会创建文件。调用 tell() 会返回当前位置;在追加模式下刚打开文件后,位置为 0 表示文件为空。只有在这种情况下才写入表头。

代码中的列名和示例数据值保留英文:

本节中的代码以及显示的标签或输出仍为英文。

from pathlib import Path
from tempfile import TemporaryDirectory

import pandas as pd

with TemporaryDirectory() as directory:
    path = Path(directory) / "records.csv"
    rows = pd.DataFrame({"name": ["Mia"], "score": [7]})

    with path.open("a", encoding="utf-8", newline="") as csv_file:
        write_header = csv_file.tell() == 0
        rows.to_csv(csv_file, header=write_header, index=False)

这种做法适用于新文件和已有 CSV:新建或空文件会写入列名,有内容的文件则只接收新行。每次追加时都应保持相同的列顺序,并使用兼容的字段。如果程序中有多个写入者可能同时更新同一文件,请协调这些写入操作,避免表头检查与行写入和其他写入交错执行。

验证追加的行并避免常见错误

需要确认文件内容时,可在写入后读取 CSV。对于第一个示例,文件中会有一个表头,后面依次是原有记录和追加的记录。运行时,print(path.read_text(), end="") 语句会将文件的实际内容显示为可选择的文本。

改用这些示例时,请检查以下事项:

  • 追加的 DataFrame 列必须与 CSV 列顺序一致。Pandas 按位置写入值;追加时不会根据列名匹配 CSV 中的列。
  • 对于已有表头的非空文件,请使用 header=False。重复的表头会被当作普通数据行读取。
  • 如果行索引不属于数据,请使用 index=False。否则,应将索引列纳入文件布局并在后续处理中考虑它。
  • 追加模式会在文件末尾添加文本;它不会验证或修复不匹配的列、分隔符或编码。请保持这些设置与现有 CSV 一致。
  • 如果文件为空,请在写入第一条数据行之前写入一次表头。上面的 tell() 检查会根据追加模式下打开的文件位置来决定是否写入表头。

如果要在 Python 中快速检查,可以用 pd.read_csv(path) 加载生成的文件,并查看其中的行和列名。这样既能验证写入磁盘的文本,也能验证解析后的表格。