# Add review comments to DOCX with python-docx

> Use python-docx 1.2.0 to anchor a review comment to runs. Understand sentence boundaries, comment authors, and the difference between comments and tracked edits.

Maintained by Vespper. Updated 2026-09-27.

Canonical page: https://www.vespper.com/guides/python-docx-comments

Topic: [Python DOCX troubleshooting](https://www.vespper.com/guides#python). [Start the learning path](https://www.vespper.com/guides#start-here).

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

```python
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](https://python-docx.readthedocs.io/en/stable/user/comments.html) 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](https://github.com/python-openxml/python-docx/issues/949) 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](https://github.com/python-openxml/python-docx/issues/1551).

Preserve existing comments when moving a document between stages.

## Next steps

- [Return edits as native revisions](https://www.vespper.com/guides/tracked-changes-api): Use tracked changes when the user needs to accept or reject an actual text replacement.
- [Build an agent editing workflow](https://www.vespper.com/guides/build-docx-editing-agent): Connect read, search, and edit tools to your application and deliver the resulting DOCX.

## Related guides

- [python-docx: create and edit Word documents in Python](https://www.vespper.com/llms/python-docx.md)