python-docx 是一个用于创建和操作 Microsoft Word（.docx）文档的 Python 库。本技能汇总了文档自动化的全面使用模式，来自生产环境文档生成系统的实践提炼。
用途
该技能适用于以下场景：以编程方式从数据创建 Word 文档；生成格式一致的报告；构建合同、发票或法律文档；自动化基于模板的文档创建；修改已有的 Word 文档；创建具有复杂表格结构的文档；生成包含代码块的技术文档；构建带页眉页脚的多节文档；创建嵌入图片和图表的文档；批量处理文档生成。
不适用于以下场景：简单的模板填充（应改用 docx-templates）；最终输出为 PDF（应改用 pypdf 或 reportlab）；需要实时协作编辑；文档需要复杂宏或 VBA；需要保留复杂的 Word 特性（Windows 上应使用 COM 自动化）；仅需要从文档中提取文本（应使用 python-docx2txt）。
主要能力
技能涵盖的内容包括：从零或模板创建文档；使用样式、字体与对齐方式设置段落格式；生成带合并单元格、样式与格式化的表格；设置带页码和动态内容的页眉与页脚；插入图片并控制尺寸与位置；管理样式以保持文档外观一致；操作模板以支持文档工作流；邮件合并模式用于批量文档生成。文档中列出了子技能：1. 基础文档创建；2. 高级段落格式化；3. 表格创建与格式化；4. 页眉、页脚与页面设置；5. 图片插入与定位；6. 样式管理与自定义样式；另外还包括从数据库生成报告、批量文档生成、文档结构等内容。
使用方式
安装命令如下：
使用 pip
pip install python-docx
使用 uv（推荐）
uv pip install python-docx
含图片支持
pip install python-docx Pillow
含所有可选依赖的完整安装
pip install python-docx Pillow lxml
安装验证代码：
from docx import Document from docx.shared import Inches, Pt, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.enum.table import WD_TABLE_ALIGNMENT
print("python-docx installed successfully!")
版本历史：1.0.0（2026-01-17）为初始技能创建，包含核心能力文档、6 个完整代码示例、集成模式、最佳实践指南和故障排查章节。
适用场景与限制
适用场景包括程序化生成文档、报告与合同自动化、模板化文档批量生成、以及修改已有文档等。限制方面，官方资料明确指出：不适合简单模板填充、PDF 生成、实时协作编辑、复杂宏或 VBA、需要保留复杂 Word 特性以及仅需文本提取的场景，这些情况应改用其他相应工具。
相关资源
官方文档：https://python-docx.readthedocs.io/ GitHub 仓库：https://github.com/python-openxml/python-docx PyPI 包：https://pypi.org/project/python-docx/ Open XML SDK 参考：https://docs.microsoft.com/en-us/office/open-xml/
相关技能：docx-templates（用于 Word 文档的 Jinja2 风格模板渲染）、pypdf（PDF 操作与生成）、openpyxl（Excel 文件自动化）、python-pptx（PowerPoint 演示文稿生成）。