python-docx

python-docx is a Python library for creating, reading, and updating Microsoft Word 2007+ (.docx) documents. It exposes a Pythonic object model — Document, Paragraph, Run, Table, Section, Styles — that maps onto the underlying Office Open XML (OOXML) format, so generating a report or editing an existing document reads like ordinary Python rather than raw XML manipulation.

Under the hood it implements the Open Packaging Conventions (the zip-based container format Word files use) and a schema-driven layer of custom lxml element classes, giving it both a friendly high-level API for common tasks and a documented escape hatch into the raw XML tree for anything the high-level API doesn’t cover yet. It’s a long-running, widely used project (5,700+ GitHub stars, over a thousand commits) that has become the de facto standard for programmatic Word document generation in Python.

What You Get

• A Document object model covering paragraphs, runs, tables, sections, styles, headers/footers, and inline images
• Round-trip editing: open an existing .docx, modify specific paragraphs or table cells, and save without disturbing the rest of the document
• Fine-grained text formatting through Run objects (bold, italic, font, color, size) and paragraph-level formatting (alignment, spacing, indentation)
• A built-in default document template so Document() with no arguments produces a ready-to-use blank document
• Direct access to the underlying OOXML tree via the oxml layer for formatting the high-level API doesn’t yet expose

Common Use Cases

• Generating invoices, contracts, or reports as .docx files from application data
• Mail-merge-style document generation — populating a Word template with per-recipient data in bulk
• Extracting or auditing text and table content from a batch of existing Word documents
• Programmatically applying consistent styles/branding across a set of generated documents

Under The Hood

Architecture

The library is built in three layers: an opc/ layer implementing the Open Packaging Conventions (zip-based reading and writing of package parts via pkgreader.py, pkgwriter.py, part.py, and phys_pkg.py), an oxml/ layer of custom lxml element classes generated declaratively through xmlchemy.py’s BaseOxmlElement and descriptor system that mirrors the ECMA-376 OOXML schema, and a high-level docx/ API (document.py, text/, table.py, section.py, styles/) that wraps oxml objects in Pythonic classes. A call like document.add_paragraph() constructs an oxml element through this chain and returns a thin wrapper around it. Because every high-level class delegates storage and mutation to the oxml layer, changes to the core xmlchemy declarative element system ripple through nearly every public class.

Tech Stack

python-docx is pure Python with two runtime dependencies — lxml (>=3.1.0) for XML parsing/serialization and typing_extensions for backported typing constructs — targeting Python 3.9+. It’s built with setuptools under a PEP 517 backend, manages development dependencies with uv (a committed uv.lock is present), and documents are built with Sphinx and published on Read the Docs. There’s no web or ORM framework involved; this is a standalone document-manipulation library.

Code Quality

The project has 59 unit-test modules under tests/ that mirror the src/docx package layout, using pytest with a custom mock/fixture utility module and a compact CXML mini-language for building XML test fixtures, following a Describe*/it_* BDD naming convention. Alongside this, roughly 70 Gherkin .feature files under features/ are run through behave as end-to-end acceptance tests against real generated .docx files. Static typing is enforced with pyright and linting with ruff; errors are raised as explicit typed exceptions rather than swallowed. Only a legacy Travis CI config is present in this snapshot rather than GitHub Actions, though tox.ini supports local multi-version test runs.

What Makes It Unique

The distinguishing technical choice is the xmlchemy declarative custom-element framework: instead of hand-writing lxml element subclasses, oxml elements are defined through descriptor-based helpers that map OOXML schema constructs (child elements, attributes, choice groups) directly onto Python class attributes. This keeps the low-level layer schema-faithful and DRY while keeping each high-level API class thin, and it gives users first-class, documented access to raw OOXML for anything the high-level API doesn’t cover. It’s a mature, disciplined pattern rather than a novel one — the value is in comprehensive, reliable coverage of the OOXML surface rather than a new paradigm.