---
id: docx-mailmerge2
version: "1.0.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# docx-mailmerge2 — Performs a Mail Merge on docx (Microsoft Office Word) files

License: permissive · Maintenance: active · Downloads: 133.1K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 133.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

docx mail merge, word document template merge, office open xml merge fields, python docx template, automated word document generation, merge fields in docx, word mailmerge python, document-automation, office-integration

[View on SkillFed](https://skillfed.io/packages/docx-mailmerge2) · [View on PyPI](https://pypi.org/project/docx-mailmerge2/)