{"id":44780,"library":"docx-mailmerge2","title":"docx-mailmerge2","description":"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.","status":"active","version":"1.0.1","language":"python","source_language":"en","source_url":"http://github.com/iulica/docx-mailmerge","tags":["docx","mail-merge","word","templates"],"install":[{"cmd":"pip install docx-mailmerge2","lang":"bash","label":"Install via pip"},{"cmd":"pip install git+https://github.com/iulica/docx-mailmerge.git","lang":"bash","label":"Install from GitHub"}],"dependencies":[{"reason":"Required for XML manipulation of docx files.","package":"lxml","optional":false},{"reason":"Required for image handling in mail merge.","package":"pillow","optional":true}],"imports":[{"note":"Common mistake: using hyphen or underscore in module name. The correct module name is 'mailmerge'.","wrong":"from docx_mailmerge import MailMerge","symbol":"MailMerge","correct":"from mailmerge import MailMerge"}],"quickstart":{"code":"from mailmerge import MailMerge\nimport os\n\ndocument = MailMerge('template.docx')\ndocument.merge(Field1='Value1', Field2='Value2')\ndocument.write('output.docx')\nprint('Mail merge completed.')","lang":"python","description":"Basic usage: Load a .docx template, merge fields, and save output."},"warnings":[{"fix":"Use standard MergeField in Word (Insert > Quick Parts > Field > MergeField).","message":"The 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.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace imports from 'docx-mailmerge' to 'docx-mailmerge2' (pip install).","message":"The original docx-mailmerge package is unmaintained (last release 2017). docx-mailmerge2 is the fork to use.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure images are inserted as InlineShapes (not floating). Use merge with dictionary: {'Image': 'path/to/image.png'}.","message":"Images in templates (e.g., placeholders like {{Image}}) require Pillow and careful handling. The library replaces inline images only; floating images may not be updated.","severity":"gotcha","affected_versions":"all"},{"fix":"Use document.merge(Field1='Value1') instead of document.merge('Value1', 'Value2').","message":"In version 1.0.0, the merge() method no longer accepts positional arguments for field values; all must be keyword arguments.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.1':23 '3.7':27 'activ':32 'cadenc':38 'current':20 'data':18 'docx':2,13,39 'docx-mailmerge2':1 'file':14 'librari':5 'mail':8,41 'mail-merg':40 'mailmerge2':3 'mainten':33 'merg':9,42 'microsoft':11 'perform':7 'project':29 'python':17,26 'regular':36 'releas':37 'standard':16 'structur':19 'support':25 'templat':44 'use':15 'version':22 'word':12,43","created_at":"2026-06-07T12:51:48.020803+00:00","updated_at":"2026-06-07T12:51:48.020803+00:00","problems":[{"fix":"Run: pip install docx-mailmerge2. Then import as: from mailmerge import MailMerge.","cause":"Library not installed or imported with wrong name.","error":"ModuleNotFoundError: No module named 'mailmerge'"},{"fix":"Verify merge field names in template using document.get_merge_fields() and use identical case/spelling.","cause":"The field name in the docx template does not match the merge argument exactly (including spaces and case).","error":"KeyError: 'MergeFieldName'"},{"fix":"Open the template in Word, remove any complex formatting or tracked changes, save as a new .docx.","cause":"The template .docx file is corrupted or contains custom XML that breaks parsing.","error":"lxml.etree.XMLSyntaxError: Opening and ending tag mismatch"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"http://github.com/iulica/docx-mailmerge","github":"http://github.com/iulica/docx-mailmerge","docs":null,"changelog":null,"pypi":null,"npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["productivity"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}