Python 写入 XLSX 文件:创建、DataFrame 导出与安全追加

把一段数据变成一份 XLSX 文件,Python 里通常分三步:建工作簿、写单元格、保存。真正需要花心思的是这三步之外的细节:数据来源是几个字面量、一张 DataFrame 还是一份已有报表;单元格要不要带类型和格式;文件是新建的,还是要在原表后面继续追加。不同场景对应的写法并不一样。

本文按场景给出可运行的示例:先用 openpyxl 和 Spire.XLS for Python 各写一个最小文件,再把 pandas DataFrame 以两种方式导出,接着演示文本、数字、日期、公式等类型的写入,然后处理最容易出错的追加场景,最后补上基础格式和多工作表。所有代码在发布前实际运行并核对过输出,示例基于 Spire.XLS for Python 16.8.2 与 pandas 3.1.1。

Spire.XLS for Python 是一套独立处理工作簿的 API:除创建和编辑外,内置公式计算引擎,支持把工作簿转换为 PDF、HTML 和图片,并可读写 XLS、XLSX、XLSB、XLSM、ODS 等格式,全程不需要安装 Microsoft Excel。本文聚焦写入部分;当任务从生成一个文件扩展成一条处理流水线时,用的就是同一套 API。

快速导航


1. 快速上手创建 XLSX 文件

先安装用到的库,按需取用即可,pip 对大小写不敏感:

1
2
pip install Spire.XLS         # Spire.XLS 示例使用
pip install openpyxl pandas # openpyxl 与 pandas 示例使用

用 Spire.XLS 写入

1
2
3
4
5
6
7
8
9
10
11
from spire.xls import Workbook, ExcelVersion

wb = Workbook()
wb.Worksheets.Clear() # 新建的工作簿默认带 3 张空表,先清掉
sheet = wb.Worksheets.Add("产品")
sheet.Range["A1"].Text = "产品"
sheet.Range["B1"].Text = "价格"
sheet.Range["A2"].Text = "键盘"
sheet.Range["B2"].NumberValue = 29.9
wb.SaveToFile("output/quickstart_spire.xlsx", ExcelVersion.Version2016)
wb.Dispose()

这段代码有两个值得留意的细节。新建的 Workbook() 默认带三张空表(Sheet1 到 Sheet3),示例先清掉再添加一张”产品”表,保存出来的文件里就只有实际写入的内容。值通过带类型的属性写入:字符串用 Text,数字用 NumberValue。这种显式赋值让单元格类型完全可控,适合构建混合数据类型的报表。SaveToFile 按指定格式落盘,Dispose 释放工作簿占用的资源,长时间运行的脚本记得调用。

用 openpyxl 写入

1
2
3
4
5
6
7
8
9
from openpyxl import Workbook

wb = Workbook()
ws = wb.active
ws["A1"] = "产品"
ws["B1"] = "价格"
ws["A2"] = "键盘"
ws["B2"] = 29.9
wb.save("output/quickstart_openpyxl.xlsx")

Workbook() 建好的文件自带一张活动表。给 ws["A1"] 赋值即写入,openpyxl 会根据 Python 值推断单元格类型:字符串落成文本,29.9 落成数字。wb.save 负责写文件。本文示例统一输出到脚本同级的 output/ 目录,运行前先建好这个目录,或者改成自己的路径。

快速上手两段代码的产出文件在 Excel 中的效果


2. 把 pandas DataFrame 导出为 XLSX 文件

多数 XLSX 文件的数据源头是一张 pandas DataFrame。导出有两条路,对应不同的后续工作。

方案 A:让 pandas 直接写文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import pandas as pd

df = pd.DataFrame({
"姓名": ["张伟", "李娜", "王芳"],
"分数": [90, 85, 78],
"价格": [12.5, 9.99, 120.75],
"注册日期": pd.to_datetime(["2026-01-15", "2026-03-02", "2026-06-30"]),
"是否有效": [True, False, True],
"备注": ["正常", None, None],
})

with pd.ExcelWriter("output/df_export.xlsx", datetime_format="YYYY-MM-DD") as w:
df.to_excel(w, index=False) # index=False 不写入行号列

# pandas 不写列宽,日期列太窄会显示成 ###
from openpyxl import load_workbook
wb = load_workbook("output/df_export.xlsx")
wb.active.column_dimensions["D"].width = 13
wb.save("output/df_export.xlsx")

index=False 去掉行号列,表头从第一行开始;ExcelWriter 的 datetime_format 把日期列统一成 YYYY-MM-DD 显示。类型在写入过程中保持不变:整数、浮点数、日期、布尔值各归其位,None 和 NaN 落成空单元格。两个显示上的坑也一并处理:pandas 默认把日期写成”日期 + 时间”共 19 个字符,窄列里只会显示 ###;列宽也是默认值。示例用 datetime_format 和三行列宽代码解决。

1
2
3
4
summary = df[["姓名", "分数"]].groupby("姓名", as_index=False).min()
with pd.ExcelWriter("output/df_multi.xlsx", datetime_format="YYYY-MM-DD") as writer:
df.to_excel(writer, sheet_name="订单", index=False)
summary.to_excel(writer, sheet_name="汇总", index=False)

DataFrame 经 to_excel 导出的结果:类型保持原样,None 落成空单元格

方案 B:把 DataFrame 交给 Spire.XLS 写入

文件只需要存在时,方案 A 到此为止。后续还要改单元格、设样式、算公式,或者把工作簿转成 PDF,Spire.XLS 可以用同一套 API 接着做。pandas 的写入引擎只支持 openpyxl 和 XlsxWriter,所以这里先桥接:df.values.tolist() 把 DataFrame 转成 Python 数据的嵌套列表,再交给 Spire.XLS 逐格写入。示例沿用方案 A 定义的 df:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
from datetime import datetime
import pandas as pd
from spire.xls import Workbook, ExcelVersion, DateTime

header = df.columns.tolist()
data = df.values.tolist()

wb = Workbook()
wb.Worksheets.Clear()
sheet = wb.Worksheets.Add("数据导出")

for j, h in enumerate(header, start=1):
sheet.Range[1, j].Text = str(h)

for i, row in enumerate(data, start=2):
for j, v in enumerate(row, start=1):
cell = sheet.Range[i, j]
if pd.isna(v): # None / NaN / pd.NA / pd.NaT 一律留空
continue
elif isinstance(v, bool):
cell.BooleanValue = v
elif isinstance(v, datetime): # pd.Timestamp 是 datetime 的子类
cell.DateTimeValue = DateTime.Parse(v.strftime("%Y-%m-%d %H:%M:%S"))
cell.NumberFormat = "yyyy-mm-dd"
elif isinstance(v, (int, float)):
cell.NumberValue = v
else:
cell.Text = str(v)

sheet.AllocatedRange.AutoFitColumns() # 不调列宽,日期会显示成 ###

wb.SaveToFile("output/df_to_spire.xlsx", ExcelVersion.Version2016)
wb.Dispose()

内层循环是一个小型类型分派器,分支顺序是刻意的。bool 要写在 int 前面,因为 Python 里 bool 是 int 的子类,否则 True 会写成数字 1。pd.Timestamp 继承自 datetime,日期列会走进这个分支,经 DateTime.Parse 写入并附带 NumberFormat,Excel 里看到的是日期而不是序列号。pd.isna 覆盖 pandas 的全部缺失值标记,包括 None、NaN、pd.NA 和 pd.NaT,命中的单元格留空。整数、浮点数和布尔值在文件里保持原类型。示例处理的是常见标量值,其他 pandas 数据类型需要补充对应的转换。

同一份 DataFrame 经 Spire.XLS 写入:日期带格式、缺失值留空

更多导出场景和参数说明,见官方教程在 Python 中将 Pandas DataFrame 导出到 Excel。


3. 向单元格写入不同类型的数据

数据是零散的几个值而不是一张表时,直接写单元格。赋给哪个属性决定单元格的类型,这是两个库日常使用中差别最大的地方。下面两段代码各自独立,先建工作簿,再写单元格,最后保存。

Spire.XLS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from spire.xls import Workbook, ExcelVersion, DateTime

wb = Workbook()
wb.Worksheets.Clear()
sheet = wb.Worksheets.Add("数据类型")

sheet.Range["A2"].Text = "文本"
sheet.Range["A3"].Text = "数字"
sheet.Range["A4"].Text = "日期"
sheet.Range["A5"].Text = "布尔"
sheet.Range["A6"].Text = "公式"

sheet.Range["B2"].Text = "普通文本"
sheet.Range["B3"].NumberValue = 123456.789
sheet.Range["B3"].NumberFormat = "#,##0.00"
sheet.Range["B4"].DateTimeValue = DateTime.Parse("2026-11-19 15:30:00")
sheet.Range["B4"].NumberFormat = "yyyy-mm-dd"
sheet.Range["B5"].BooleanValue = True
sheet.Range["B6"].Formula = "=B3/2"

sheet.AllocatedRange.AutoFitColumns() # 数字和日期列调宽后才能完整显示

wb.SaveToFile("output/datatypes_spire.xlsx", ExcelVersion.Version2016)
wb.Dispose()

openpyxl:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from datetime import datetime
from openpyxl import Workbook

wb = Workbook()
ws = wb.active

ws["A2"] = "文本"
ws["A3"] = "数字"
ws["A4"] = "日期"
ws["A5"] = "布尔"
ws["A6"] = "公式"

ws["B2"] = "普通文本"
ws["B3"] = 123456.789
ws["B4"] = datetime(2026, 11, 19, 15, 30)
ws["B5"] = True
ws["B6"] = "=B3/2"

ws.column_dimensions["B"].width = 14

wb.save("output/datatypes_openpyxl.xlsx")

Spire.XLS 按类型使用专用属性:字符串用 Text,数字用 NumberValue,日期用 DateTimeValue,布尔值用 BooleanValue,公式用 Formula。openpyxl 则根据赋的 Python 值自动推断。NumberFormat 控制显示格式,示例里数字用 #,##0.00,日期用 yyyy-mm-dd。

日期有一个容易浪费时间的细节:DateTimeValue 接收 Spire 的 DateTime 对象而不是 Python 的 datetime。把它和 Workbook 类一起导入(from spire.xls import DateTime),用 DateTime.Parse("2026-11-19 15:30:00") 或 DateTime.get_Now() 构造;DateTime(年, 月, 日) 这种构造形式在这个包里不可用。

公式方面,两个库写入的都是公式表达式本身。写公式和算公式是两回事:Excel 打开文件时会按自动计算得到结果,openpyxl 自身不做计算。Spire.XLS 可以算,保存前调用 wb.CalculateAllValue(),计算结果随文件一起落盘,openpyxl 以 data_only=True 读取时能直接拿到值,不必打开 Excel。

添加超链接(Spire.XLS):

1
2
3
4
5
6
7
8
9
10
11
12
from spire.xls import Workbook, ExcelVersion

wb = Workbook()
wb.Worksheets.Clear()
sheet = wb.Worksheets.Add("链接")

link = sheet.HyperLinks.Add(sheet.Range["A1"]) # 注意是大写 L
link.TextToDisplay = "e-iceblue"
link.Address = "https://www.e-iceblue.com/"

wb.SaveToFile("output/hyperlink_spire.xlsx", ExcelVersion.Version2016)
wb.Dispose()

二维列表写入时,openpyxl 有捷径:ws.append(row) 一次写一行。Spire.XLS 则按行循环,套用 DataFrame 示例里的类型分派逻辑,把每个值赋给 sheet.Range[row, col]。列表与字典的各种转换形态,在将 Python 列表转换为 Excel 表格(3 种实用场景)一文中有专门讲解。

写入文本、数字、日期、布尔与公式后的单元格,各自带显示格式


4. 向已有文件追加数据

追加是最容易出错的操作,原因是一个共同盲区:openpyxl 的 ws.max_row 和 Spire.XLS 的 sheet.LastRow 都按”已分配单元格”计数,只设过格式但没有内容的行同样计入。一张数据到第 2 行、格式刷到第 9 行的表,两个属性都会返回 9。直接往 max_row + 1 写,新记录会落到离表格七行远的空白区里。

两个库的解法一致:选一列作为记录的标志位,比如订单号或时间戳,从表头往下扫描,找到最后一个非空单元格,从它的下一行开始写。下面两段示例都这样做,并且兼容记录之间出现空行的情况。

Spire.XLS 动态追加(源文件中含格式行与空行,已实测):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
from datetime import datetime
from spire.xls import Workbook, DateTime

def append_rows(src, dst, new_rows, key_col=1):
"""扫描关键列定位最后一条有效记录,从下一行开始写入。
跳过空行和只有格式的行,兼容记录之间的空档。
行值支持 None(留空)、布尔、数字、datetime 和字符串(经 str() 转换)。"""
wb = Workbook()
wb.LoadFromFile(src)
sheet = wb.Worksheets["订单数据"] # 与 openpyxl 示例按名称取同一张表
last_row = sheet.AllocatedRange.LastRow # 含格式行,只作扫描上界
last_data_row = 1 # 表头行
r = 2
while r <= last_row:
v = sheet.Range[r, key_col].Value
if v is None or str(v).strip() == "":
has_more = False # 关键列为空不代表下方没有数据
rr = r + 1
while rr <= last_row:
vv = sheet.Range[rr, key_col].Value
if vv is not None and str(vv).strip() != "":
has_more = True
break
rr += 1
if not has_more:
break
r = rr
continue
last_data_row = r
r += 1
for i, row in enumerate(new_rows, start=last_data_row + 1):
for j, v in enumerate(row, start=1):
cell = sheet.Range[i, j]
if v is None:
continue # None 留空
elif isinstance(v, bool):
cell.BooleanValue = v
elif isinstance(v, datetime):
cell.DateTimeValue = DateTime.Parse(v.strftime("%Y-%m-%d %H:%M:%S"))
cell.NumberFormat = "yyyy-mm-dd"
elif isinstance(v, (int, float)):
cell.NumberValue = v
else:
cell.Text = str(v)
wb.SaveToFile(dst)
wb.Dispose()
return last_data_row + len(new_rows)

append_rows("orders.xlsx", "orders_updated.xlsx", [[1005, "陈晨", 77.7]])

函数接收源路径、目标路径和新行。它从第 2 行开始扫描关键列,第 1 行视为表头;AllocatedRange.LastRow 因为包含格式行,只用作扫描上界。遇到关键列为空会继续向下确认,数据可能在空档之后恢复。新行从 last_data_row + 1 写入,None 留空,字符串经 str() 转换,其余值按类型分派到 BooleanValue、NumberValue、DateTimeValue 或 Text。函数返回新的末行行号。只有表头没有记录的空表,第一条记录落在第 2 行。

openpyxl 同思路的实现(已实测):

1
2
3
4
5
6
7
8
9
10
11
12
13
from openpyxl import load_workbook

wb = load_workbook("orders.xlsx")
ws = wb["订单数据"]
last = 1
for r in range(2, ws.max_row + 1): # max_row 也计入格式行,不能直接 +1
value = ws.cell(r, 1).value
if value is not None and str(value).strip() != "":
last = r
ws.cell(last + 1, 1, 1005)
ws.cell(last + 1, 2, "陈晨")
ws.cell(last + 1, 3, 77.7)
wb.save("orders_updated.xlsx") # 输出到独立文件,源文件保持不动

同样按第 1 列扫描,max_row 限定循环范围,只有真正有内容的单元格才更新 last,判断条件与 Spire.XLS 版本一致。两个示例都把 1005、陈晨、77.7 写到现有数据的下一行,各自保存到独立的输出文件。

pandas 的 mode="a" 实际做什么。 pd.ExcelWriter(path, mode="a", engine="openpyxl", if_sheet_exists=...) 并不会把行追加到表尾,引擎读取现有工作簿后整体重写。"overlay" 保留同名工作表,新 DataFrame 从左上角第一行开始写入;由于 to_excel() 默认带表头,表头和前几行会被覆盖。"replace" 先清空同名工作表再写入。引擎不支持的内容(如图表)会在这个过程中丢失。要在现有数据下方加记录,上面按关键列扫描的方式才可靠。

源工作簿与追加结果对比:新记录落在现有数据的下一行


5. 写入时设置格式与管理多个工作表

一份报表通常需要这几样:加粗表头、数字格式、合适的列宽,再加一张汇总表。两个库都能覆盖,下面的示例从零构建一份小报表,可独立运行。

Spire.XLS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from spire.xls import Workbook, ExcelVersion, Color, HorizontalAlignType

wb = Workbook()
wb.Worksheets.Clear()
sheet = wb.Worksheets.Add("报表")

data = [["区域", "销售额"], ["东区", 15000], ["西区", 9500]]
for i, row in enumerate(data, start=1):
for j, v in enumerate(row, start=1):
cell = sheet.Range[i, j]
if isinstance(v, (int, float)) and not isinstance(v, bool):
cell.NumberValue = v
else:
cell.Text = str(v)

header = sheet.Range[1, 1, 1, 2] # A1:B1 一次性设置样式
header.Style.Font.IsBold = True
header.Style.Font.Size = 12
header.Style.Color = Color.get_LightGray()
header.Style.HorizontalAlignment = HorizontalAlignType.Center
sheet.Range[2, 2, 3, 2].NumberFormat = "¥#,##0.00"
sheet.AllocatedRange.AutoFitColumns() # 一次调整所有已用列

# 多工作表
summary = wb.Worksheets.Add("汇总")
summary.Range["A1"].Text = "汇总"

wb.SaveToFile("output/format_spire.xlsx", ExcelVersion.Version2016)
wb.Dispose()

表头区域 A1:B1 一次赋值完成样式设置,金额单元格使用货币 NumberFormat。AllocatedRange.AutoFitColumns() 一次调整所有已用列的宽度;工作表级的 AutoFitColumn() 一次只调一列,需要单独控制某列时用它。当格式规则要跟随单元格的值自动变化时,就是条件格式的领域,参见使用 Python 设置 Excel 格式:从基础到专业应用。

openpyxl:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill

wb = Workbook()
ws = wb.active

ws.append(["区域", "销售额"])
ws.append(["东区", 15000])
ws.append(["西区", 9500])

ws["A1"].font = Font(bold=True, size=12)
ws["A1"].fill = PatternFill("solid", fgColor="D3D3D3")
ws["B2"].number_format = "¥#,##0.00"
ws["B3"].number_format = "¥#,##0.00"

summary = wb.create_sheet("汇总")
summary["A1"] = "汇总"
wb.save("output/format_openpyxl.xlsx")

openpyxl 侧对应地在单元格上设置字体和填充,number_format 控制显示,create_sheet 添加汇总表,与 Spire.XLS 的 wb.Worksheets.Add("汇总") 一一对应。

设置表头样式与货币格式后的报表,汇总表已添加


6. 常见问题

怎么把 pandas DataFrame 导出为 XLSX 文件?

单表用 df.to_excel("文件.xlsx", index=False);导出多张工作表时把多次 to_excel 放进同一个 pd.ExcelWriter 上下文。导出之后还要设置格式、计算公式或转 PDF 的,用 df.values.tolist() 转成 Python 数据后交给 Spire.XLS 写入,见第 2 节方案 B。pandas 的写入引擎只有 openpyxl 和 XlsxWriter,不存在 engine="spire" 这种用法。

追加数据会覆盖原有内容吗?

写固定单元格(如 Range["A5"])会覆盖该单元格的现有内容。按关键列扫描定位最后一条记录、从下一行写入的方式不会覆盖,第 4 节的两个示例都是这种实现。另外 pandas 的 mode="a" 配合 if_sheet_exists="overlay" 会从工作表左上角开始覆写,表头行也在覆盖范围内。

Python 列表怎么写进 XLSX 文件?

openpyxl 每行调用一次 ws.append(row);Spire.XLS 逐格赋值,走带类型的属性。字典列表等更复杂的列表形态,见第 3 节链接的列表转换专题。

写入公式后读文件取不到值,为什么?

两个库写入的都是公式表达式,Excel 打开文件时才会计算。Spire.XLS 默认保存的公式不带缓存值:保存前调用 wb.CalculateAllValue(),openpyxl 用 data_only=True 读取时就能拿到计算结果。

一个 XLSX 文件里怎么写多个工作表?

openpyxl 用 wb.create_sheet("汇总");Spire.XLS 用 wb.Worksheets.Add("汇总"),新建的工作簿记得先用 wb.Worksheets.Clear() 清掉默认的三张空表;pandas 在同一个 ExcelWriter 上下文里用不同的 sheet_name 多次写入。


7. 总结

写 XLSX 文件是一组可复用的动作:建工作簿、写带类型的值、保存;文件已存在时,先找到最后一条记录再动笔。本文覆盖了这些动作最常见的变体,也把默认空表、公式缓存值、格式行撑大 max_row 这几个容易踩的坑落到了代码里。生成的报表需要导出为 PDF 或图片时,同一套 Spire.XLS API 可以直接完成。如需在无功能限制的环境下运行本文全部示例,可申请临时许可证。