docx-mailmerge2

What it is and what it does

docx-mailmerge2 is a Python library that automates the population of Microsoft Word templates by replacing merge fields with data. It reads docx files, identifies MERGEFIELD placeholders, substitutes them with values you provide, and writes the result to a new docx file—all without needing Microsoft Office installed. The library handles simple field replacement, table row templating (expanding or replacing rows based on data lists), and template duplication with page or section breaks between copies.

The package supports field formatting for numeric, text, conditional, and date values, and can work with nested fields like INCLUDEPICTURE and IF statements (though these may require manual field updates in Word afterward). It offers configuration options to control empty table removal, field preservation, automatic field updates on document open, and conditional field evaluation. The single runtime dependency is lxml, making it lightweight and portable across systems.

Use it for:

• Generate personalized letters or invoices by merging customer data into Word templates without manual editing.
• Create bulk reports by duplicating a template for each data record and separating them with page breaks.
• Populate dynamic tables in docx files by expanding template rows with lists of records.
• Automate document generation in server-side applications where Microsoft Office is unavailable.
• Preserve merge fields in output documents for later re-merging or manual updates in Word.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Performs mail merge operations on docx files by replacing merge fields with data, without requiring Microsoft Office to be installed.

Yes. The package is actively maintained, has no known vulnerabilities, carries a permissive MIT license, and solves a real problem (docx templating without Office) with low install friction. It is suitable for production use in document automation workflows, particularly where server-side generation or batch processing is needed.

Install

docx-mailmerge2 on PyPI

pip install docx-mailmerge2

uv add docx-mailmerge2

poetry add docx-mailmerge2

Installing docx-mailmerge2

Before you install

Low friction install with a single lightweight dependency (lxml). Actively maintained with recent releases; last commit 2026-06-19 and latest release 2025-12-28. Supports Python 3.7 through 3.13.

License in practice

MIT license (permissive) allows free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install docx-mailmerge2

from docx_mailmerge2 import MailMerge
with MailMerge('input.docx') as document:
    document.merge(field1='value1', field2='value2')
    document.write('output.docx')

Merge fields in the docx template must be created using CTRL-F9 (or CMD-F9 on macOS) in Microsoft Word, not as ordinary text.

Verify before relying

• Whether nested field updates (e.g., INCLUDEPICTURE, IF fields) work without opening the output in Microsoft Word to trigger F9 refresh.
• Performance characteristics when merging large numbers of rows or templates in a single operation.
• Compatibility with docx files created by non-Microsoft tools (LibreOffice, Google Docs).

Package facts

Evidence: docx_mailmerge2-1.0.1-py3-none-any.whl

Keywords: docx, office, openxml, word

Tags

More Text Processing packages