使用fitz库向PDF插入图片触发AttributeError报错如何解决

问题场景 #

需求为实现批量向多个PDF文件插入图片，先编写单个PDF文件的测试代码验证逻辑，运行时触发AttributeError报错：'Page' object has no attribute 'InsertImage'，测试代码如下：

import fitz
doc = fitz.open("example.pdf")
rect = fitz.Rect(0,0,100,100)
for Page in doc:
    Page.insertImage(rect, filename = "image1.jpg")
doc.save("new.pdf")  

排查思路 #

• 优先核对方法名拼写规范：PyMuPDF（即导入的fitz库）的公开方法统一遵循小写下划线的蛇形命名规则，大驼峰格式的InsertImage不符合库的命名习惯，首先排查大小写、拼写格式错误
• 校验库安装正确性：确认安装的是官方pymupdf包，而非同名的第三方无关fitz包，避免API不匹配
• 核对版本适配性：如果方法名拼写正确仍报错，检查本地安装的PyMuPDF版本，过旧版本可能存在API差异

解决方法 #

核心错误为方法名拼写错误：不存在驼峰命名的insertImage/InsertImage方法，插入图片的正确方法名为全小写下划线分隔的insert_image。
修正后可正常运行的代码如下：

import fitz
doc = fitz.open("example.pdf")
rect = fitz.Rect(0, 0, 100, 100)
# 遍历页面时变量名建议小写，避免和Page类名冲突
for page in doc:
    # 调用正确命名的insert_image方法
    page.insert_image(rect, filename="image1.jpg")
doc.save("new.pdf")
doc.close()  # 操作完成后关闭文档，释放文件句柄

批量实现扩展提示 #

单文件逻辑验证通过后，只需要在外层增加目标PDF文件路径的遍历循环，对每个文件依次执行打开、逐页插图、保存、关闭操作即可实现批量处理。
如果修正方法名后仍提示属性不存在，执行以下命令重装最新版官方PyMuPDF即可：
pip uninstall -y fitz pymupdf && pip install pymupdf

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