简介：本资源为 Python-docx 三方库的完整安装包及配套源码集合，面向 Python 初中级开发者、自动化办公实践者及文档处理需求者，解决在无 Microsoft Office 环境下跨平台读写 .docx 文件的核心问题。压缩包共含 1209 个文件，以 548 个 Python 源码（.py）为主干，辅以 144 个 reStructuredText 文档（.rst）、118 个功能测试用例（.feature）、94 个 XML 配置与模板文件，以及 78 个示例 .docx 文档和 20+ 张测试图像（bmp/png/jpg），全面覆盖库的构建、测试、文档与示例场景；整体大小为 11.6MB。目前已有 11403 人学习下载，资源包含可直接运行的 setup.cfg 构建配置、RST 格式官方文档源、多系统兼容的测试用例集，以及涵盖创建文档、编辑段落、插入图片/表格、修改样式等全链路操作的实操示例，是理解与深度使用 python-docx 的高质量工程级参考包。
1. Python-docx 不是 Office 自带功能：它让纯 Python 脚本在无 Word 环境下生成、修改 .docx 文件，适合批量合同生成、自动化报告、CI/CD 文档流水线等场景
你有没有遇到过这种需求：服务器上跑着一个 Python 服务，要根据数据库内容动态生成几十份带表格、标题、页眉页脚的 Word 报告，但服务器压根没装 Microsoft Word，甚至不是 Windows 系统？这时候python-docx就不是“可选库”，而是唯一能落地的方案。它不依赖 COM 接口、不调用 office 进程、不走 OLE 容器黑盒，而是直接操作 Open XML 标准（ISO/IEC 29500）定义的 .docx 文件结构——本质上，它把 .docx 当成一个 ZIP 包来读写，里面是/word/document.xml、/word/styles.xml、/word/media/等标准目录。这意味着它天然跨平台（Linux/macOS/Windows 均可）、轻量（无 GUI 开销）、可嵌入 Docker 容器、能和 Flask/FastAPI 无缝集成。但它也不是万能胶：不能打开 .doc（旧二进制格式），不支持宏、域代码（如 TOC 自动生成）、修订模式或密码保护文档；如果你要处理的是用户上传的、含复杂分栏/文本框/嵌入 Excel 表格的 Word，它大概率会丢内容。所以它的定位非常清晰：面向开发者，为程序生成“结构化、可预测、可版本控制”的 Word 文档而生，不是替代人工编辑的 Word 替身。本文就带你从零拆解这个包怎么装、怎么用、哪些地方一碰就翻车、以及如何绕过它的设计边界稳稳交付。
2. 安装与环境适配：pip install python-docx 是起点，但版本、依赖、系统差异决定你能不能真正 import docx
2.1 pip 安装命令与版本选择逻辑
最简安装命令是：
pip install python-docx但注意：这个包在 PyPI 上的名字叫python-docx，而它的源码仓库名、GitHub 主页、甚至 import 语句里的模块名都是docx—— 这个命名错位是历史遗留问题，别被pip show python-docx输出的Name: python-docx和import docx的不一致搞懵。当前稳定版是0.8.11（截至 2024 年中），它基于lxml解析 XML，比早期纯xml.etree版本快 3–5 倍，且对中文样式兼容更好。如果你用的是 Python 3.12+，请确认lxml已预编译支持（某些 Alpine Linux 镜像需额外装libxml2-dev libxslt-dev）。不建议降级到0.8.10及以下，因为0.8.10在处理含<w:br>换行符的段落时有内存泄漏，某次批量生成 500 份报告时进程 RSS 内存涨到 2.3GB 后被 OOM killer 杀掉——这是血泪经验。
2.2 验证安装是否真正成功：三步检测法
光pip install成功不等于能用。执行以下三步验证：
# step1: 检查基础 import 是否通过 try: from docx import Document print("✅ import docx 成功") except ImportError as e: print("❌ import 失败:", e) # step2: 检查 lxml 是否可用（底层依赖） try: from lxml import etree print("✅ lxml 可用，etree 版本:", etree.LXML_VERSION) except ImportError: print("❌ lxml 缺失，请先 pip install lxml") # step3: 创建最小文档并保存（真机测试） try: doc = Document() doc.add_paragraph("test") doc.save("/tmp/test.docx") print("✅ 文档创建+保存成功，路径:/tmp/test.docx") except Exception as e: print("❌ 文档操作失败:", type(e).__name__, str(e))提示：第三步必须做。曾有某 CentOS 7 环境
import成功，但Document()报OSError: [Errno 2] No such file or directory: '/usr/lib64/python3.6/site-packages/docx/templates/default.docx'——原因是 rpm 包管理器安装的python3-docx未包含模板文件，必须用pip重装覆盖。
2.3 虚拟环境与多 Python 版本下的安装陷阱
如果你机器上同时装了 Python 3.8、3.10、3.12，且用pyenv或conda管理：
pip install python-docx默认只装到当前激活的 Python 环境；python3.10 -m pip install python-docx和python3.12 -m pip install python-docx是两条独立命令，不能混用；- 某次在 CI 流水线中，
.yml里写pip install python-docx，但 runner 使用的是python:3.12-slim镜像，该镜像默认没装gcc，导致lxml编译失败，报错error: command 'gcc' failed with exit status 1。解决方案是在pip install前加：
apt-get update && apt-get install -y build-essential libxml2-dev libxslt-dev注意：不要用
--only-binary=lxml强制二进制安装，某些 ARM64 架构（如 Apple M1/M2）的预编译 wheel 不全，反而更易失败。
3. 核心 API 实战：从新建文档到插入表格、图片、页眉页脚，每一步都带参数含义说明
3.1 新建空白文档与加载已有 .docx
Document()构造函数有两种用法：
from docx import Document # 方式1：新建空白文档（使用内置 default.docx 模板） doc = Document() # ✅ 最常用 # 方式2：加载已有 .docx 文件（路径必须存在且可读） doc = Document("input.docx") # ✅ 支持相对/绝对路径 # 方式3：加载自定义模板（比如你改过字体/页边距的 .docx） doc = Document("my_template.docx") # ✅ 模板中的样式会被继承关键点：Document()加载时会解析整个 XML 结构树，包括所有段落、表格、节、页眉页脚。如果input.docx有 100 页、含 50 张嵌入图，加载耗时可能达 2–3 秒——这不是 bug，是 Open XML 解析的固有开销。若只需读取文字内容，建议用python-docx的Document().paragraphs+p.text循环，而非先加载再删内容。
3.2 插入段落与控制格式：style 参数是核心，不是可选项
# 添加普通段落（无样式） p = doc.add_paragraph("这是普通段落") # 添加带样式的段落（强烈推荐！否则格式不可控） p = doc.add_paragraph("这是标题1", style="Heading 1") p = doc.add_paragraph("这是正文", style="Normal") p = doc.add_paragraph("这是强调文本", style="Intense Emphasis") # 查看当前文档所有可用样式名（调试必备） for style in doc.styles: print(style.name, "→", style.type) # type: 1=paragraph, 2=character, 3=table为什么 style 必须显式指定？因为
python-docx不维护“默认样式栈”。如果你不写style=，它会用Normal，但Normal的字体、字号、行距取决于你加载的模板（default.docx 或自定义模板）。某次某高校教务系统导出课表 Word，开发人员本地用add_paragraph("课程名称")，测试环境却显示为 18 号加粗——查出是测试机上的default.docx被运维误更新过。从此我们团队强制所有add_paragraph必带style=，哪怕写style="Normal"。
3.3 表格操作：行列插入、单元格合并、样式绑定
# 创建 3 行 4 列表格 table = doc.add_table(rows=3, cols=4, style="Table Grid") # 获取第0行第0列单元格，并写入文本 cell = table.cell(0, 0) cell.text = "第一行第一列" # 合并单元格：从 (0,0) 到 (0,2)（即第0行，第0~2列） cell.merge(table.cell(0, 2)) # 给整行设背景色（需用底层 XML 操作） row = table.rows[0] tr = row._tr trPr = tr.get_or_add_trPr() shd = trPr.get_or_add_shd() shd.val = "solid" shd.color = "D3D3D3" # 浅灰 shd.fill = "D3D3D3"注意：
table.cell(row, col)的索引从 0 开始，且merge()只接受cell对象，不能传坐标。合并后原cell(0,1)和cell(0,2)仍存在，但.text读出来是空字符串——这是 Open XML 规范要求，合并后的单元格只保留左上角 cell 的内容。
3.4 插入图片与尺寸控制：width/height 单位是 EMU，不是像素
# 插入图片（路径必须存在） doc.add_picture("chart.png", width=Inches(6), height=Inches(4)) # 或用 Cm 单位（更符合国内习惯） from docx.shared import Cm doc.add_picture("logo.jpg", width=Cm(5), height=Cm(2)) # ⚠️ 关键：width/height 是“显示尺寸”，不是原始图尺寸 # 如果原始图是 300dpi 的 1200×800 像素图，设 width=Cm(10) 会自动缩放，不损失画质Inches()和Cm()是docx.shared模块提供的单位转换器，内部将厘米转为 EMU（English Metric Unit，1 英寸 = 914400 EMU）。不建议用px，因为 Word 中像素不是绝对单位；也不建议只设width不设height，否则图片会变形（Word 默认保持纵横比，但python-docx不自动计算，需手动算好比例）。
4. 避坑：5 个高频翻车现场，现象、原因、解决全写透
4.1 现象：中文乱码，段落显示为方框或问号
原因：python-docx默认使用+mn-lt（拉丁文）字体，未显式设置中文字体时，Windows 上 fallback 到 SimSun，macOS fallback 到 Helvetica，Linux fallback 到 DejaVu Sans——这些字体不一定含中文字符集。
解决：
- 方案1（推荐）：全局设置 Normal 样式字体
style = doc.styles['Normal'] font = style.font font.name = 'SimSun' # Windows font._element.rPr.rFonts.set_qn('w:eastAsia', 'SimSun') - 方案2：给每个段落单独设字体
p = doc.add_paragraph("中文标题") run = p.runs[0] run.font.name = 'Microsoft YaHei' run._element.rPr.rFonts.set_qn('w:eastAsia', 'Microsoft YaHei')
4.2 现象：生成的 .docx 在 Word 里打开提示“文件已损坏，尝试修复？”
原因：XML 结构非法，最常见于：
- 手动修改
cell._tc等底层 XML 元素后，未调用cell._tc._insert_tcPr(tcPr)导致<w:tcPr>缺失； - 插入图片时路径错误（如
"./img/logo.png"但当前工作目录不对），python-docx会静默跳过，但 XML 中残留<w:drawing>占位符，破坏结构完整性。
解决： - 永远用
doc.add_picture()而非手动构造<w:drawing>； - 修改底层 XML 后，用
doc.save()前先执行doc._body._body.clear()清理缓存（不推荐，仅应急）； - 生产环境加校验：保存后用
zipfile.is_zipfile()检查是否为合法 ZIP，再用zipfile.ZipFile().namelist()确认含word/document.xml。
4.3 现象：页眉页脚不显示，或只在首页出现
原因：Word 的页眉页脚是按“节（Section）”划分的，默认只有一个节，但python-docx创建新节时不会自动复制页眉页脚。
解决：
# 获取第一节（通常就是默认节） section = doc.sections[0] header = section.header header.is_linked_to_previous = False # 断开与前节链接（如有） header.paragraphs[0].text = "这是页眉" # 若需不同页眉（如奇偶页不同），需启用： section.different_first_page_header_footer = True section.even_page_header.is_linked_to_previous = False4.4 现象：表格内文字换行失效，所有内容挤在一行
原因：python-docx默认关闭单元格自动换行（<w:tcW>宽度设为固定值），且未设置<w:textDirection>。
解决：
cell = table.cell(0, 0) # 方法1：设为自动宽度 tc = cell._tc tcPr = tc.get_or_add_tcPr() tcW = tcPr.get_or_add_tcW() tcW.w = 0 # 0 表示自动宽度 tcW.type = 'auto' # 方法2：强制换行（在文本中插入 \n） cell.text = "第一行\n第二行" # ✅ 有效4.5 现象：doc.save("out.docx")报PermissionError: [Errno 13] Permission denied
原因：目标路径被其他进程占用（如 Word 正在打开该文件、IDE 的预览窗格锁住文件、杀毒软件实时扫描）。
解决：
- 永远 save 到临时路径，再 move：
import tempfile, shutil tmp_path = tempfile.mktemp(suffix=".docx") doc.save(tmp_path) shutil.move(tmp_path, "final.docx") # move 是原子操作，几乎不锁文件 - 或用
os.replace()（Python 3.3+）：os.replace(tmp_path, "final.docx")
5. 进阶技巧：用自定义 XML 注入绕过限制，实现 TOC、超链接、页码等原生不支持功能
5.1 为什么原生不支持目录（TOC）？
python-docx的设计哲学是“只操作内容，不操作域代码”。TOC 在 Word 中本质是{ TOC \o "1-3" \h \z \u }这类域代码，它在文档中以<w:fldChar w:fldCharType="begin"/>开头，<w:instrText>存指令，<w:fldChar w:fldCharType="end"/>结尾。python-docx不解析也不生成这类结构，因为它无法保证域代码刷新逻辑（需 Word 手动 F9 或打印触发）。但生产环境常需 PDF 导出前生成静态 TOC，怎么办？
5.2 手动注入 TOC XML 的完整步骤
我们不生成域代码，而是生成“静态 TOC”——即把标题文字、页码（需提前知道）拼成普通段落。难点在于页码获取。方案是：先用python-docx生成内容 → 用docx2python库提取所有标题及位置 → 用pdfplumber提取 PDF 页码 → 回填到 Word。但更轻量的做法是：用lxml直接向document.xml插入<w:p>段落模拟 TOC。以下是安全注入的最小可行代码：
from docx import Document from lxml import etree doc = Document() # 先添加真实内容（假设已有3个标题） doc.add_heading("第一章 引言", level=1) doc.add_heading("第二章 方法", level=1) doc.add_heading("第三章 结果", level=1) # 保存为临时文件以便 lxml 修改 tmp_path = "/tmp/temp.docx" doc.save(tmp_path) # 解压 .docx，修改 document.xml import zipfile, os, tempfile with zipfile.ZipFile(tmp_path, 'r') as zin: with zipfile.ZipFile("/tmp/out.docx", 'w') as zout: # 复制所有非 document.xml 文件 for item in zin.filelist: if item.filename != "word/document.xml": zout.writestr(item.filename, zin.read(item.filename)) # 读取并修改 document.xml xml_content = zin.read("word/document.xml") root = etree.fromstring(xml_content) # 找到 <w:body>，在其开头插入 TOC 段落 body = root.find('.//{http://schemas.openxmlformats.org/wordprocessingml/2006/main}body') # 构造 TOC 段落 XML（简化版，仅文字+页码） toc_p = etree.Element("{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p") toc_r = etree.SubElement(toc_p, "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}r") toc_t = etree.SubElement(toc_r, "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t") toc_t.text = "目 录\n第一章 引言 ........................................... 1\n第二章 方法 ........................................... 3\n第三章 结果 ........................................... 5" body.insert(0, toc_p) # 插入到 body 最前面 # 写回 zout.writestr("word/document.xml", etree.tostring(root, encoding='UTF-8', xml_declaration=True)) # 替换原文件 os.replace("/tmp/out.docx", "final_with_toc.docx")这段代码的关键在于：
- 不用
docx模块的 API，而是直操作 XML，规避了python-docx的抽象层限制；- 页码
1/3/5是硬编码，实际项目中应由docx2python提取标题位置后计算（每段落高度≈12pt，A4 页面约 50 行，可估算）；toc_t.text中的.用全角空格或 更美观，但python-docx不处理 HTML 实体，所以直接用 ASCII 点+空格。
5.3 插入超链接：比 TOC 更简单，只需<w:hyperlink>
# 在段落中插入超链接（无需外部库） p = doc.add_paragraph() run = p.add_run("点击访问官网") # 构造 hyperlink XML ns = {'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'} hyperlink = etree.SubElement(p._p, '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}hyperlink', { 'r:id': 'rId1', 'w:history': '1' }) # 添加链接文本 r = etree.SubElement(hyperlink, '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}r') t = etree.SubElement(r, '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t') t.text = "点击访问官网" # 在 document.xml.rels 中添加关系（省略，需 zip 操作）但生产中更推荐用docx2python+python-docx组合：先用docx2python读取原始含链接的 docx，提取hyperlink关系，再复用到新文档——避免手写 rels。
从那以后我每次生成正式交付文档，都会在doc.save()后加一步：用zipfile打开输出文件，检查word/document.xml是否含<w:hyperlink>或<w:tbl>标签，再用docx2python读一遍文本，确认关键标题和数字没丢。这多花 0.3 秒，但省去客户说“你们的 Word 打不开”的 2 小时排查。希望帮到你。
本文还有配套的精品资源，点击获取
