{"id":4937,"library":"docxcompose","title":"docxcompose","description":"docxcompose is a Python library for concatenating/appending Microsoft Word (.docx) files. It extends `python-docx` to facilitate merging documents while preserving complex formatting, styles, headers, and footers. The current version is 2.1.0, with a release cadence of several updates per year.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/4teamwork/docxcompose","tags":["docx","word","document processing","merge","compose","ooxml","python-docx"],"install":[{"cmd":"pip install docxcompose","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core library for interacting with .docx files, which docxcompose extends.","package":"python-docx","optional":false},{"reason":"XML parsing, typically a dependency of python-docx.","package":"lxml","optional":false},{"reason":"Tools for internationalizing Python applications.","package":"babel","optional":false}],"imports":[{"symbol":"Composer","correct":"from docxcompose.composer import Composer"},{"symbol":"Document","correct":"from docx import Document"}],"quickstart":{"code":"from docxcompose.composer import Composer\nfrom docx import Document\nimport os\n\n# Create dummy master and sub documents for demonstration\n# In a real scenario, these would be existing .docx files\n\n# Master document\nmaster = Document()\nmaster.add_heading('Master Document Title', level=0)\nmaster.add_paragraph('This is the content of the master document.')\nmaster.add_paragraph('It may contain its own headers and footers.')\nmaster.save('master.docx')\n\n# Sub document 1\ndoc1 = Document()\ndoc1.add_heading('Section 1', level=1)\ndoc1.add_paragraph('Content from the first appended document.')\ndoc1.save('doc1.docx')\n\n# Sub document 2\ndoc2 = Document()\ndoc2.add_heading('Section 2', level=1)\ndoc2.add_paragraph('More content from the second appended document.')\ndoc2.save('doc2.docx')\n\n# Compose documents\nmaster_doc = Document('master.docx')\ncomposer = Composer(master_doc)\n\n# Append documents\ncomposer.append(Document('doc1.docx'))\ncomposer.append(Document('doc2.docx'))\n\n# Save the combined document\ncomposer.save('combined.docx')\n\nprint(\"Documents composed and saved to 'combined.docx'\")\n\n# Clean up dummy files (optional)\nos.remove('master.docx')\nos.remove('doc1.docx')\nos.remove('doc2.docx')","lang":"python","description":"This quickstart demonstrates how to initialize a master document, create additional documents, and then use the `Composer` to append them sequentially, saving the result to a new file."},"warnings":[{"fix":"Design your master document with the desired headers and footers for the entire merged output. Manually copy elements if specific headers/footers from sub-documents are required.","message":"Headers and footers from appended documents are ignored. Only the headers and footers of the *first* (master) document are used in the merged file.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review merged documents carefully. Consider simplifying complex elements in sub-documents or using alternative merging strategies for files with such content.","message":"Merging documents with complex elements like SmartArt or custom properties can result in corrupted output documents. This is an open issue.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test compatibility on your target Python version before deployment. If encountering issues, consider downgrading `docxcompose` or upgrading your Python interpreter to 3.12+.","message":"Despite PyPI indicating compatibility with Python >=3.10, some users have reported that recent versions (possibly 2.x) unexpectedly require Python 3.12 or newer.","severity":"breaking","affected_versions":"Potentially 2.0.0 and newer"},{"fix":"Add `--collect-data \"docxcompose\"` to your PyInstaller command.","message":"For applications bundled with PyInstaller, you may need to explicitly collect `docxcompose` data to avoid runtime errors (e.g., `pyinstaller --collect-data \"docxcompose\" your_script.py`).","severity":"gotcha","affected_versions":"All versions when bundled with PyInstaller"},{"fix":"Consider optimizing your workflow if dealing with extremely large files, or break down the merging task into smaller chunks if feasible.","message":"Processing very large documents can be slow and consume moderate memory, as documents are processed sequentially and stored in memory.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}