Install & Compatibility
Where this runs
tested against v1.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
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.198s · 32.8MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.3s · import 0.177s · 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 to interact with Word documents is 'Document', imported from the top-level 'docx' package. Avoid 'import docx' directly without further specifying the class, as it's not the primary entry point for document objects. Also, do not name your script 'docx.py' to avoid circular import errors.
Inches
✓ from docx.shared import Inches
✗ width=2
When specifying measurements for elements like images, use units from `docx.shared` (e.g., `Inches`, `Cm`) to ensure correct scaling. Providing raw integer values will result in extremely small dimensions.
This quickstart demonstrates how to create a new Word document, add a title, paragraphs with styled text (bold, italic), insert an image, create a simple table, and add a page break. It saves the resulting document as 'demo.docx'. Ensure you have an 'image.png' file or remove the `add_picture` line to run without error.
from docx import Document
from docx.shared import Inches
document = Document() # Create a new, blank Word document
document.add_heading('Document Title', 0)
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
document.add_heading('Heading, level 1', level=1)
document.add_paragraph('Intense quote', style='Intense Quote')
document.add_picture('image.png', width=Inches(1.25)) # Add an image (ensure 'image.png' exists)
table = document.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Item'
hdr_cells[2].text = 'Description'
document.add_page_break()
document.save('demo.docx')
print("Document 'demo.docx' created successfully.")
Debug
Known issues
breakingPython 2 support was removed starting with version 1.0.0. The library now requires Python 3.7 or newer. Attempts to use it with Python 2 will result in errors.fixUpgrade to Python 3.7 or a newer compatible version.
affects: 1.0.0 and above
gotchaThe PyPI package name for this actively maintained library is `python-docx`, while an older, unmaintained package exists under the name `docx` (version 0.2.4, last updated 2009). This entry is for the actively developed `python-docx` as indicated by the provided GitHub URL. Installing `pip install docx` will give you the old, abandoned library.fixAlways use `pip install python-docx` to get the correct and actively maintained library.
affects: All versions of `python-docx`
gotchaNaming your Python script file `docx.py` can cause a `ModuleNotFoundError` or `AttributeError` due to a circular import conflict with the `docx` module itself. The interpreter tries to import from your script instead of the installed library.fixRename your script file to something other than `docx.py` (e.g., `my_document_script.py`).
affects: All versions
gotchaWhen modifying existing documents, especially those with complex layouts, merged cells in tables, or specific styles, preserving original formatting can be challenging. Directly copying and modifying elements with `python-docx` might lead to unexpected formatting changes or document corruption if not handled carefully.fixFor complex template-based document generation or modifications, consider generating tables and content programmatically rather than attempting direct in-place modification of highly structured template elements. Inspect the generated XML if issues persist.
affects: All versions
Upgrade
Version history
1.2.0latest on PyPI · released Jun 16, 2025
Audit
Dependencies
lxmlrequiredRequired for XML parsing and manipulation of .docx files. pip automatically handles this dependency.