使用python-docx添加图片有数量限制吗？批量添加后Word提示文档损坏

一、使用Python操作DOCX文档时，添加图片是否存在无错误的数量限制？ #

• 本身没有固定的硬数量限制，主要受以下因素影响：
  • 文档格式规范：DOCX基于OOXML标准，只要生成的文件符合规范，理论上可支持大量图片；
  • 内存资源：添加大量图片时，Python进程内存占用会上升，极端场景可能出现内存不足问题；
  • 库的实现细节：不同DOCX处理库（如python-docx）的逻辑存在差异，部分场景可能出现边界问题，但并非是“数量限制”本身导致。

二、python-docx添加多张图片后Word提示文档损坏的原因及解决办法 #

原因分析 #

核心问题是重复添加同一张本地图片时，python-docx的图片引用处理存在瑕疵：
多次调用add_picture添加同一张图片时，库会重复将图片嵌入DOCX包，但生成文档的关系文件（.rels）或图片元数据时，可能出现重复ID或不规范的引用记录，导致Word校验文档完整性时触发“损坏”提示——但图片数据本身完整，因此点击确认后可正常显示。

解决办法 #

有两种可靠处理方式：

1. 复用图片二进制数据，避免重复嵌入

读取一次图片的二进制内容，多次添加时复用该数据，减少重复嵌入并规避引用冲突：

import docx
from docx import Document
from docx.shared import Inches

document = Document("TEST.docx")

# 读取图片二进制数据
with open("test.jpg", "rb") as img_file:
    img_data = img_file.read()

# 循环复用数据添加图片
for _ in range(8):
    document.add_picture(img_data, width=Inches(7.0))

document.save("TEST_Output.docx")

2. 复制含图片的段落（适用于格式完全一致的场景）

先添加一张图片到段落，再复制该段落多次，避免重复处理图片嵌入逻辑：

import docx
from docx import Document
from docx.shared import Inches

document = Document("TEST.docx")

# 添加第一张图片到段落
paragraph = document.add_paragraph()
run = paragraph.add_run()
run.add_picture("test.jpg", width=Inches(7.0))

# 复制段落7次（最终共8张图片）
for _ in range(7):
    new_paragraph = document.add_paragraph()
    new_paragraph._p.append(paragraph._p[0].copy())

document.save("TEST_Output.docx")

额外验证步骤

• 升级python-docx到最新版本：执行pip install --upgrade python-docx，旧版本可能存在此类已知的引用处理bug；
• 尽量使用较新的Word版本，新版本对OOXML的兼容性和容错性更好。

内容的提问来源于stack exchange，提问作者Arno