Install & Compatibility
Where this runs
tested against v1.0.2 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.192s · 32.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.3s · import 0.176s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Document
✓ from docx import Document
✗ import docx
The primary class `Document` is imported from the `docx` module, not the top-level package name `python-docx-ml6`. Attempting to `import docx` directly will not provide access to the `Document` class without further qualification.
This quickstart demonstrates how to create a new Word document, add headings, paragraphs with formatted text (bold/italic), insert an image, and create a simple table. It then saves the document to a .docx file.
from docx import Document
from docx.shared import Inches
# Create a new document
document = Document()
# Add a heading
document.add_heading('Document Title', level=0)
# Add a paragraph
p = document.add_paragraph('A plain paragraph having some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True
# Add a heading with level 1
document.add_heading('Heading, level 1', level=1)
# Add a picture
document.add_picture('path/to/image.png', width=Inches(1.25))
# Add a table
records = (
(3, '101', 'Spam'),
(7, '422', 'Eggs'),
(4, '631', 'Spam, eggs, and bacon'),
)
table = document.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'
for qty, id, desc in records:
row_cells = table.add_row().cells
row_cells[0].text = str(qty)
row_cells[1].text = id
row_cells[2].text = desc
document.add_page_break()
# Save the document
document.save('demo.docx')
print("Document 'demo.docx' created successfully.")
Debug
Known issues
gotchaThis library is a fork (`python-docx-ml6`) of the original `python-docx`. While it includes additional community-requested features, users migrating from the original `python-docx` or expecting identical behavior should verify specific functionalities, as there might be subtle differences or a divergent maintenance path.fixConsult the `python-docx-ml6` GitHub repository's README or issue tracker for specific features and differences. Explicitly install `python-docx-ml6` if its features are desired, rather than the original `python-docx`.
affects: All versions
gotchaSaving a document to an existing filename will silently overwrite the original file without any warning or prompt.fixImplement explicit checks in your code (e.g., `os.path.exists`) or save to unique filenames to prevent accidental data loss.
affects: All versions
gotchaWhen replacing text or placeholders in a document, simple methods might only affect the first occurrence within a paragraph or run. Achieving global or multiple replacements often requires iterating through paragraphs and runs.fixFor comprehensive text replacement, iterate through `document.paragraphs`, `paragraph.runs`, or other document elements, checking and replacing text as needed, rather than relying on high-level single-call replacement functions if they exist.
affects: All versions
breakingIf migrating from very old versions of `python-docx` (0.2.x or earlier), be aware that versions 0.3.0 and later introduced significant API incompatibilities. While `python-docx-ml6` is a fork of a modern `python-docx`, this historical context is relevant for deep migrations.fixRefer to the `python-docx` changelog for migration guides if coming from ancient versions. Expect a rewrite of document manipulation logic if transitioning from pre-0.3.0 code.
affects: < 0.3.0 (original python-docx)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'docx'
The package `python-docx-ml6` was installed, but the Python interpreter cannot find the `docx` module. This often happens if the package wasn't installed in the active environment, or if an older, unmaintained package named `docx` was accidentally installed instead of `python-docx-ml6`.
fixFirst, ensure `python-docx-ml6` is installed in your active Python environment (`pip install python-docx-ml6`). Then, verify its presence (`pip show python-docx-ml6`). If you previously installed a package called `docx` (which is deprecated), uninstall it (`pip uninstall docx`) and reinstall `python-docx-ml6`.
Deprecation Warning: This code will cease to work in future versions.
This warning typically originates from an underlying dependency like `lxml`, or from using an older version of `python-docx` (or its fork `python-docx-ml6`) that had known deprecation issues. For instance, specific `python-docx` versions before 0.8.11 had a known deprecation warning.
fixUpgrade `python-docx-ml6` and its core dependencies to their latest stable versions: `pip install --upgrade python-docx-ml6 lxml`. Review the library's GitHub issues for any specific known deprecations in the current version.
AttributeError: 'Document' object has no attribute 'some_feature'
The user might be expecting a feature that exists in the original `python-docx` or a different fork, or conversely, a feature that only exists in `python-docx-ml6` but is not present in the user's installed version or is called differently. This highlights the fork's specific feature set.
fixConfirm the installed version of `python-docx-ml6` (`pip show python-docx-ml6`). Consult the `ml6team/python-docx` GitHub repository for the specific API and features supported by this fork. If the feature is expected from the original `python-docx`, consider if `python-docx-ml6` has a different implementation or if the feature is simply not included in the fork.
Upgrade
Version history
1.0.2latest on PyPI · released Nov 9, 2023
Audit
Dependencies
lxmlrequiredRequired for parsing and generating Office Open XML (OOXML) files.
typing-extensionsoptionalProvides backported and experimental type hints for Python.