Add review comments to DOCX with python-docx

python-docx 1.2.0 can add a Word review comment with Document.add_comment. A comment is anchored to runs. To annotate an exact sentence inside a larger run, first split the text into appropriate run boundaries while preserving the existing formatting and document structure.

A comment records feedback; it does not turn an ordinary text replacement into a tracked insertion or deletion. Choose the review artifact your user needs before implementing the feature.

Add a comment to a known run

from docx import Document

doc = Document()
p = doc.add_paragraph("Delivery: ")
target = p.add_run("Confirm the final date.")
comment = doc.add_comment(
    runs=target,
    text="Please confirm this date with the project owner.",
    author="Review assistant",
    initials="RA",
)
assert comment.text == "Please confirm this date with the project owner."
assert comment.author == "Review assistant"

Save the document to a separate output file in your application, then open it in Word to inspect the anchor and comment. This small example deliberately creates the target sentence as its own run, so it does not need a general sentence-splitting algorithm.

Handle existing paragraphs carefully

Real paragraphs may split a sentence across several runs or put several sentences into one run. Locate the selected character range, map it to runs, and create valid boundaries before adding the comment. The comments documentation explains anchoring constraints and unsupported locations.

Do not recreate a mixed paragraph from paragraph.text just to obtain a convenient anchor. That can remove hyperlinks, drawings, and character formatting. Test repeated sentences so that a comment is attached to the occurrence the user selected rather than the first textual match.

Keep the author and purpose explicit

Use the application's real review identity in the comment metadata. Comment text should explain the issue and the requested decision, for example “Confirm whether this date includes the review period.” A vague “AI suggestion” comment gives the reviewer little useful context.

The historical sentence-comment request is evidence of this workflow need, not evidence that current python-docx lacks comments. Check examples against the installed API; documentation inconsistencies have also been reported and closed.

Preserve existing comments when moving a document between stages.