python-docx (Microsoft Word .docx files)

1.2.0 verified Tue May 12 auth: no en install: verified quickstart: stale

python-docx is a Python library for creating, reading, and updating Microsoft Word 2007+ (.docx) files. It provides an object-oriented API to interact with the structure and content of Word documents. The library is actively maintained, with regular releases addressing features and bug fixes.

pip install python-docx

Warnings

breaking Python 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. ↓

fix Upgrade to Python 3.7 or a newer compatible version.

gotcha The 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. ↓

fix Always use `pip install python-docx` to get the correct and actively maintained library.

gotcha Naming 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. ↓

fix Rename your script file to something other than `docx.py` (e.g., `my_document_script.py`).

gotcha When 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. ↓

fix For 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.17s 32.7M

3.10 alpine (musl) - - 0.17s 32.8M

3.10 slim (glibc) wheel 2.3s 0.11s 33M

3.10 slim (glibc) - - 0.12s 33M

3.11 alpine (musl) wheel - 0.25s 34.7M

3.11 alpine (musl) - - 0.28s 34.9M

3.11 slim (glibc) wheel 2.3s 0.23s 35M

3.11 slim (glibc) - - 0.22s 35M

3.12 alpine (musl) wheel - 0.21s 26.7M

3.12 alpine (musl) - - 0.22s 26.8M

3.12 slim (glibc) wheel 2.1s 0.20s 27M

3.12 slim (glibc) - - 0.20s 27M

3.13 alpine (musl) wheel - 0.19s 26.4M

3.13 alpine (musl) - - 0.22s 26.5M

3.13 slim (glibc) wheel 2.2s 0.19s 27M

3.13 slim (glibc) - - 0.19s 27M

3.9 alpine (musl) wheel - 0.15s 32.2M

3.9 alpine (musl) - - 0.15s 32.3M

3.9 slim (glibc) wheel 2.6s 0.15s 33M

3.9 slim (glibc) - - 0.13s 33M

Imports

Document
wrong
```
import docx
```
correct
```
from docx import Document
```
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
wrong
```
width=2
```
correct
```
from docx.shared import Inches
```
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.

Quickstart stale last tested: 2026-04-24

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.")