paper-docx
github.com/paper-instruments/paper-docx- Category
- Developer Tools
- Rank
- No. 1270Tools index
Previous survey · No. 1283 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Productivity & Collaboration
- Interfaces
- CLI
- GitHub
- 136 stars
- Latest release
- v0.2.1
- Date
About
paper-docx is an import-compatible hard fork of python-docx for creating and editing Microsoft Word (.docx) documents, built to be "agent-safe." It keeps the same docx import name and object model but adds guarded inspection and editing APIs that refuse unsupported operations instead of silently guessing, which the project states cuts DOCX generation failures by 78% compared to the original library; installation replaces python-docx in the same environment and adds a paper_docx_doctor diagnostic command.
At a glance
paper-docx keeps the familiar Python docx import and adds guarded operations for editing Word documents. It is worth evaluating when an automation needs to reject an unsupported edit before it changes a document.
Good fit
Python developers maintaining document workflows that need visible redlines or explicit failures.
Consider something else when
Keep your existing setup if you cannot isolate the fork or check that representative files survive your edits.
Start here
Compare two disposable documents with one paragraph changed. Open the redline in Word and verify the tracked changes and nearby formatting.
Cost and requirements
Python package. It shares the docx import with python-docx, so test it in a separate environment.
Limits to know
Some document operations are intentionally refused. Check tracked changes and complex formatting on the actual document types you need to handle.
Sources checked 2026-11-05. Source-based assessment.
Read the source review
What it does
A Python library for Word files that slots in where python-docx was, so existing code keeps working while new modules sit on top. They read every part of a file, including footnotes, text boxes and pending tracked changes, find text across the fragments Word splits it into, edit it in place, accept or reject revisions, and produce a native redline from two versions. Every new operation either does exactly what it says or refuses and leaves the file untouched.
Why it's ranked here
Agents editing Word files usually fail quietly: the file opens, but the edit landed in the wrong run or dropped a tracked change. This fork targets that failure directly with typed refusals and rollback on error, while keeping the upstream object model and MIT license. The added surface is large and documented in unusual detail, from cross-document copying to protection-aware editing. The verdict leans on that documentation, because the fetched code covers the install guard rather than the editing engine.
What's good
The safety promises are specific. Mutations validate before touching anything or restore the captured state, so a refusal leaves the document unchanged. Search matches exact visible text by default and makes loose matching an explicit opt-in. The redline generator proves both the accept and reject outcomes on private copies before returning. A narrow save path restores the original bytes of every XML part whose meaning did not change, which keeps diffs reviewable. Editing honours Word's restrict-editing modes, so a comments-only document still takes comments but refuses body edits.
Tradeoffs
It replaces python-docx rather than sitting beside it: both claim the same import name, and the bundled doctor command fails if both are installed, so any dependency that pins python-docx will conflict. The strictness has a cost. Edits that cross wrapper boundaries, span paragraphs or meet ambiguous alignment refuse instead of guessing, so callers need a retry path. Compare falls back to coarse whole-block revisions when a changed region holds more than one block. Fields such as page numbers are written as formulas and only computed when Word opens the file.
How to use it well
Install it in a fresh virtual environment after uninstalling python-docx, and run the doctor check after install and in deployment scripts. It fits agents and pipelines that revise contracts or reports and must hand back tracked changes a person can accept or reject. Prefer the narrow save over a full save when editing an existing file, and catch the refusal type separately from ordinary errors. For documents built from scratch, the upstream API is still the whole story. It does not render or convert files; layout and field values stay Word's job.
Technical notes+
src/docx/__init__.py calls assert_distribution_identity() from docx._version before importing anything else, keeps the upstream __version__ of 1.2.0 next to __paper_version__, and registers the commentsExtended, commentsIds and commentsExtensible content types as plain XmlPart so threaded-comment metadata survives a load. src/paper_docx_doctor/__init__.py verifies the install before importing docx: it fails if python-docx metadata exists, rehashes every docx file listed in the wheel RECORD using hmac.compare_digest, rejects absolute or parent-relative RECORD paths, confirms docx.__file__ resolves inside the owned root, then compares the version sentinel. pyproject.toml enables pyright strict mode and pytest warnings-as-errors. docs/api/paper-package.rst says the public docx.package names wrap private modules.
Observed
- License
- MIT, inherited from python-docx, with fork additions under a separate copyright line
- Language
- Python, requires 3.9 or later
- Packaging
- PyPI distribution paper-docx; import name stays docx
- Runtime dependencies
- lxml and typing_extensions only
- Interfaces
- Python library plus a paper-docx-doctor console command
- Coexistence
- Cannot be installed alongside python-docx in one environment
- Type checking
- pyright strict mode configured in pyproject.toml
- Declared maturity
- Development Status 5, Production/Stable classifier
- Platform support
- OS Independent classifier
Read from README.md, pyproject.toml, LICENSE, src/docx/__init__.py, src/paper_docx_doctor/__main__.py, src/paper_docx_doctor/__init__.py, docs/user/paper-additions.rst, docs/api/paper-composition.rst, docs/api/paper-revisions.rst, docs/api/paper-protection.rst, docs/api/paper-package.rst, docs/user/quickstart.rst.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.