Registry / productivity / docx-mailmerge2

docx-mailmerge2

JSON →
library1.0.1pypypi✓ verified 88d ago

A library to perform mail merge on Microsoft Word .docx files using standard Python data structures. Currently at version 1.0.1, it supports Python >=3.7. The project is under active maintenance with no regular release cadence.

productivity
pip install docx-mailmerge2
github ↗homepage ↗
INSTALL
IMPORT
SIG · DOCX-MAILMERGE2
D
docx-mailmerge2
productivitypythonv1.0.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MailMerge
✓ from mailmerge import MailMerge
✗ from docx_mailmerge import MailMerge
Common mistake: using hyphen or underscore in module name. The correct module name is 'mailmerge'.

Basic usage: Load a .docx template, merge fields, and save output.

from mailmerge import MailMerge import os document = MailMerge('template.docx') document.merge(Field1='Value1', Field2='Value2') document.write('output.docx') print('Mail merge completed.')
Debug
Known issues
gotchaThe library modifies the template's 'merge fields' (MERGEFIELD) in docx. Make sure the template does NOT have 'MustMerge' fields or other non-standard field types.
fix
Use standard MergeField in Word (Insert > Quick Parts > Field > MergeField).
affects: all
deprecatedThe original docx-mailmerge package is unmaintained (last release 2017). docx-mailmerge2 is the fork to use.
fix
Replace imports from 'docx-mailmerge' to 'docx-mailmerge2' (pip install).
affects: >=1.0.0
gotchaImages in templates (e.g., placeholders like {{Image}}) require Pillow and careful handling. The library replaces inline images only; floating images may not be updated.
fix
Ensure images are inserted as InlineShapes (not floating). Use merge with dictionary: {'Image': 'path/to/image.png'}.
affects: all
breakingIn version 1.0.0, the merge() method no longer accepts positional arguments for field values; all must be keyword arguments.
fix
Use document.merge(Field1='Value1') instead of document.merge('Value1', 'Value2').
affects: >=1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mailmerge'
Library not installed or imported with wrong name.
fix
Run: pip install docx-mailmerge2. Then import as: from mailmerge import MailMerge.
KeyError: 'MergeFieldName'
The field name in the docx template does not match the merge argument exactly (including spaces and case).
fix
Verify merge field names in template using document.get_merge_fields() and use identical case/spelling.
lxml.etree.XMLSyntaxError: Opening and ending tag mismatch
The template .docx file is corrupted or contains custom XML that breaks parsing.
fix
Open the template in Word, remove any complex formatting or tracked changes, save as a new .docx.
Upgrade
Version history
1.0.1latest on PyPI · released Dec 28, 2025
Audit
Dependencies
lxmlrequiredRequired for XML manipulation of docx files.
pillowoptionalRequired for image handling in mail merge.
Agent activity
32 hits · last 30 days
node
30
OpenAI (training)
1
Resources
githubhttp://github.com/iulica/docx-mailmerge ↗
homepagehttp://github.com/iulica/docx-mailmerge ↗
docx-mailmerge2 — pip install docx-mailmerge2 · libregistry