python-docx is an excellent library that stops at a well-defined boundary. Past that boundary — the style cascade, content controls, anchored comments, tracked changes, custom numbering, table borders — the usual answer is a StackOverflow snippet that reaches into element._p and builds raw lxml by hand. Everyone writing serious document automation ends up with a private, half-tested pile of that code.

docx_plus is that pile, done properly: typed, tested against documents Word itself authored, and schema-strict about where elements are allowed to go. It composes with python-docx rather than replacing it — you keep your Document object and reach for docx_plus only where you need to.

from docx import Document
from docx_plus.styles import resolve_effective_formatting

doc = Document("report.docx")

# "Why is this heading 13pt and blue?" — a question python-docx can't answer,
# because the value is inherited, not set on the paragraph at all.
resolved = resolve_effective_formatting(doc.paragraphs[0], include_provenance=True)

print(resolved.font_size)                # 13.0
print(resolved.provenance["font_size"])  # FormattingSource(layer='paragraphStyle',
                                         #                  style_id='Heading2',
                                         #                  chain_depth=0, ...)

Install

pip install docx-plus

uv add docx-plus

Requires Python 3.10+. The only dependencies are python-docx and lxml.

What it does

Quickstart

Four of the most-used surfaces, each with a link to its full guide. Every capability has one — see the guides index — plus runnable examples under docx_plus/examples/.

Styles: define once, apply everywhere

from docx import Document
from docx_plus.styles import apply_style, create_style, ensure_style

doc = Document()
create_style(
    doc, "BrandHeading",
    style_type="paragraph",
    based_on="Heading1",
    font_name="Inter",
    font_size=18.0,
    color_rgb="2F5496",
    bold=True,
    spacing_after=240,
)
apply_style(doc.add_paragraph("Hello, world"), "BrandHeading")
doc.save("out.docx")

This is the Word-native workflow: define a style, apply it. Change the style later and every paragraph using it follows — unlike direct formatting, which you have to remember to update everywhere. ensure_style materialises any of Word's 107 latent built-ins with defaults extracted from real Word-saved samples, and remap_styles reconciles documents authored elsewhere that call the same style "Heading 1".

→ Styles guide

Forms: build a fillable document

from docx_plus.controls import FormBuilder

fb = FormBuilder()  # or FormBuilder("template.docx")
fb.doc.add_heading("New employee form", level=1)

p = fb.doc.add_paragraph("Full name: ")
fb.add_text_control(p, tag="full_name", placeholder="Type your name")

p = fb.doc.add_paragraph("Department: ")
fb.add_dropdown(p, tag="dept", items=["Engineering", "Design", "Ops"])

p = fb.doc.add_paragraph("Start date: ")
fb.add_date_picker(p, tag="start_date", date_format="M/d/yyyy")

fb.save("form.docx")

Read and update an existing form's values:

from docx import Document
from docx_plus.controls import read_controls, set_control_value

doc = Document("form.docx")
set_control_value(doc, "full_name", "Ada Lovelace")
doc.save("filled.docx")

values = read_controls(Document("filled.docx"))
print(values["full_name"].value)   # 'Ada Lovelace'

→ Forms guide — including protect_document(mode="forms") to lock everything but the controls.

Comments: anchored to the text they're about

from docx import Document
from docx_plus.comments import add_comment, read_comments, reply_to_comment

doc = Document()
p = doc.add_paragraph()
p.add_run("Project Apollo ")
target = p.add_run("ships next quarter")

c = add_comment(target, "Optimistic — let's see what QA says.", author="Alice")
reply_to_comment(doc, c.comment_id, "Agreed, moving to Q3.", author="Bob")

for comment in read_comments(doc):
    print(f"{comment.author}: {comment.text!r} on {comment.anchored_text!r}")

add_comment accepts a Run, a Paragraph, or a (start_run, end_run) tuple for ranges. Unlike python-docx's Comments.add_comment — which writes only the part-side body — docx_plus writes the three body-side anchors, so the comment is attached to a real span of text.

→ Comments guide

Publishing: TOC, captions, Table of Figures

from docx import Document
from docx_plus.fields import mark_fields_dirty
from docx_plus.publishing import add_caption, add_table_of_figures, add_toc

doc = Document()
doc.add_heading("Contents", level=1)
add_toc(doc.add_paragraph(), levels=(1, 2))

doc.add_heading("Architecture", level=1)
cap = doc.add_paragraph()
add_caption(cap, "Figure ", caption_type="Figure")
cap.add_run(": System overview.")

doc.add_heading("List of Figures", level=1)
add_table_of_figures(doc.add_paragraph(), caption_type="Figure")

mark_fields_dirty(doc)   # Word populates TOC / SEQ / ToF on open
doc.save("paper.docx")

That mark_fields_dirty call is not optional — every field the library writes (TOC, captions, cross-references, page numbers, dates) renders blank on disk until Word recalculates it.

→ Publishing guide

The rest

Tracked changes, tables, numbering, layout, bookmarks, footnotes, and the linter each have their own guide:

Command line

docx-plus installs a console command (also python -m docx_plus.cli) for inspecting and editing documents from a shell:

$ docx-plus inspect report.docx --provenance        # effective formatting per paragraph
$ docx-plus restyle draft.docx --target Heading1 -o clean.docx
$ docx-plus controls list form.docx --json          # every content control
$ docx-plus controls set form.docx --tag name --value "Ada Lovelace" -o filled.docx
$ docx-plus comments list draft.docx --unresolved   # open comment threads
$ docx-plus lint report.docx                        # formatting defects
$ docx-plus plan report.docx                        # what repairing them would change
$ docx-plus skill install                           # drop the agent skill into .claude/skills/

Read commands take --json. Mutating commands require -o/--output (or an explicit --in-place) so the source is never overwritten by accident. lint and plan exit 1 when they found something, so either drops into a CI step directly. Full reference: CLI docs.

For AI coding agents

docx_plus ships an agent skill inside the package — a structured guide to the API that Claude Code (or any agent that reads skill files) can load instead of guessing at signatures. pip install docx-plus is enough to get it:

$ docx-plus skill install      # copies it into ./.claude/skills/

See docx_plus/skill/SKILL.md and the skills overview.

Documentation

Full docs are published at https://thomas-villani.github.io/docx-plus/, built with MkDocs and mkdocstrings.

• Getting started — install, your first script, and the seven conventions that apply across every module. Start here.
• Guides — one task-oriented page per capability: styles, forms, comments, tracked changes, tables, publishing, linting, and the rest.
• Concepts — the cascade algorithm, schema-strict insertion, the parts model, the error hierarchy, and the invariants the library maintains. Read this if you want to know why the OOXML looks the way it does.
• API index — hand-curated index of every public symbol, linked to the generated reference.
• CLI reference.
• Test gaps — an honest accounting of where the suite has real holes.

Project status

v0.6.1, released 2026-08-21 — beta, and shipping. 2,098 tests, 96% coverage, mypy --strict clean with zero ignores. CI runs Python 3.10–3.13 on Linux plus a Windows job, and a lower-bound dependency job pinned to python-docx==1.0.0 / lxml==4.9.0.

The API is stable in practice but pre-1.0: breaking changes are possible on minor versions and will be called out in CHANGELOG.md.

ROADMAP.md is the live record of what is shipped, backlogged, and deliberately declined. Currently on the backlog: content-control data binding to Custom XML Parts, bibliography and BIBLIOGRAPHY fields, theme writing, glossary placeholder text, and password-protected forms. If your use case needs one of these, open an issue — demand reorders the list.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development setup, the quality gates, and the conventions. In short:

git clone https://github.com/thomas-villani/docx-plus.git
cd docx-plus
uv sync --extra dev
uv run pre-commit install
uv run pytest

Bug reports are most useful with a minimal .docx attached, or the offending fragment of word/document.xml.

Security issues should be reported privately — see SECURITY.md.

License

MIT. Copyright (c) 2026 Tom Villani, PhD. See LICENSE.