docxcompose

library2.2.0pypypi✓ verified 24d ago

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.

serialization data

pip install docxcompose

package ↗

INSTALL

IMPORT

SIG · DOCXCOMPOSE

docxcompose

serializationpythonv2.2.0

Install

2.9s avg

Import

239ms

Disk

64MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.254s · 65.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.9s · import 0.224s · 66MB

64MB installed

● package 64MB

Code

Verified usage

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

Composer

✓ from docxcompose.composer import Composer

Document

✓ from docx import Document

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.

from docxcompose.composer import Composer from docx import Document import os # Create dummy master and sub documents for demonstration # In a real scenario, these would be existing .docx files # Master document master = Document() master.add_heading('Master Document Title', level=0) master.add_paragraph('This is the content of the master document.') master.add_paragraph('It may contain its own headers and footers.') master.save('master.docx') # Sub document 1 doc1 = Document() doc1.add_heading('Section 1', level=1) doc1.add_paragraph('Content from the first appended document.') doc1.save('doc1.docx') # Sub document 2 doc2 = Document() doc2.add_heading('Section 2', level=1) doc2.add_paragraph('More content from the second appended document.') doc2.save('doc2.docx') # Compose documents master_doc = Document('master.docx') composer = Composer(master_doc) # Append documents composer.append(Document('doc1.docx')) composer.append(Document('doc2.docx')) # Save the combined document composer.save('combined.docx') print("Documents composed and saved to 'combined.docx'") # Clean up dummy files (optional) os.remove('master.docx') os.remove('doc1.docx') os.remove('doc2.docx')

Debug

Known issues

gotchaHeaders and footers from appended documents are ignored. Only the headers and footers of the *first* (master) document are used in the merged file.

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.

affects: All versions

gotchaMerging documents with complex elements like SmartArt or custom properties can result in corrupted output documents. This is an open issue.

fix

Review merged documents carefully. Consider simplifying complex elements in sub-documents or using alternative merging strategies for files with such content.

affects: All versions

breakingDespite PyPI indicating compatibility with Python >=3.10, some users have reported that recent versions (possibly 2.x) unexpectedly require Python 3.12 or newer.

fix

Test compatibility on your target Python version before deployment. If encountering issues, consider downgrading `docxcompose` or upgrading your Python interpreter to 3.12+.

affects: Potentially 2.0.0 and newer

gotchaFor 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`).

fix

Add `--collect-data "docxcompose"` to your PyInstaller command.

affects: All versions when bundled with PyInstaller

gotchaProcessing very large documents can be slow and consume moderate memory, as documents are processed sequentially and stored in memory.

fix

Consider optimizing your workflow if dealing with extremely large files, or break down the merging task into smaller chunks if feasible.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'docxcompose'

The 'docxcompose' library is not installed in your Python environment, or there is a typo in the import statement.

fix

Install the library using pip: `pip install docxcompose`. Ensure your import statement is correct, typically `from docxcompose.composer import Composer`.

AttributeError: 'DocumentPart' object has no attribute '_numbering_part'

This error typically indicates an incompatibility between the installed version of 'docxcompose' and its dependency 'python-docx'. An expected internal attribute (`_numbering_part`) is missing or named differently in the 'python-docx' library.

fix

First, try upgrading 'docxcompose' to the latest version: `pip install --upgrade docxcompose`. If the issue persists, you may need to pin your 'python-docx' version to a known compatible one, such as `pip install python-docx==0.8.11`, or consult the 'docxcompose' GitHub issues for specific compatibility notes.

AttributeError: 'NoneType' object has no attribute 'xpath'

This error occurs when 'docxcompose' attempts to call the `xpath` method on an object that is `None`. This usually means a specific XML element or a part of the DOCX document structure that 'docxcompose' expects to find is missing, not correctly parsed, or cannot be located in the input `.docx` file, often due to malformed or unexpected document content.

fix

Verify the integrity and standard compliance of the input `.docx` files. Ensure they are not corrupted and have a consistent structure. If the documents are generated programmatically, ensure all necessary XML elements are present. Simplifying complex or non-standard document features might also help resolve the issue.

Upgrade

Version history

2.2.0latest on PyPI · released Jun 2, 2026

Audit

Dependencies

python-docxrequiredCore library for interacting with .docx files, which docxcompose extends.

lxmlrequiredXML parsing, typically a dependency of python-docx.

babelrequiredTools for internationalizing Python applications.

Agent activity

64 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/docxcompose/ ↗