python-docx

1.2.0 · active · verified Sat Mar 28

python-docx is a Python library for creating, reading, and updating Microsoft Word (.docx) files. It allows programmatic manipulation of Word documents without requiring Microsoft Word or similar software to be installed. The current version is 1.2.0, and the project is actively maintained.

Warnings

breaking API Incompatibility with older versions: `python-docx` versions 0.3.0 and later are not API-compatible with prior versions. Significant changes were introduced.
Fix: Review the official documentation and rewrite code leveraging the newer API for versions 0.3.0 and above. Upgrading from very old versions will require code changes.
gotcha Styles applied via `python-docx` might not appear in the generated document if the style definition is not present in the starting .docx file (template). Word silently ignores undefined styles.
Fix: Ensure that any custom styles you intend to use are pre-defined in your base .docx template document. For built-in styles, the default template usually suffices, but for custom ones, they must exist in the document's `styles.xml` part.
gotcha Overwriting files: When opening and saving a document with the same filename, `python-docx` will overwrite the original file without any warning or confirmation.
Fix: Always save to a new filename or implement explicit checks and user confirmation in your application logic if overwriting is a concern. Consider creating backups of critical files before modification.
gotcha PermissionError when saving: You may encounter 'PermissionError: [Errno 13] Permission denied' if the .docx file you are trying to save is open in Microsoft Word or another application, or if your script lacks sufficient write permissions for the target directory.
Fix: Ensure the target .docx file is closed in all applications before your script attempts to save to it. Verify that your script has appropriate write permissions for the directory. Use a `try-except` block to gracefully handle `PermissionError`.
gotcha Complex tables and templates: Manipulating documents, especially those created from templates with complex tables (e.g., merged cells), can lead to unexpected XML errors or issues with content insertion and preservation.
Fix: For highly complex layouts, it's often more robust to read the necessary data from the template and programmatically reconstruct tables and content using `python-docx` rather than directly attempting to modify intricate template structures. If you need template-like variable substitution, consider `python-docx-template` which is built on `python-docx` and designed for this purpose.

Install

pip install python-docx Install stable version

Imports

Document
```
from docx import Document
```
While `import docx` is technically possible, you would then need to refer to the class as `docx.Document`. The common and recommended pattern is to directly import `Document`.

Quickstart

This quickstart demonstrates how to create a new Word document, add a top-level heading, a paragraph with styled text (bold and italic), and a basic table with a predefined style, then save it to a .docx file.

from docx import Document

# Create a new document
document = Document()

# Add a heading
document.add_heading('My Awesome Document', level=0)

# Add a paragraph
p = document.add_paragraph('This is a simple paragraph with some ')
p.add_run('bold text').bold = True
p.add_run(' and some ')
p.add_run('italic text').italic = True

# Add a table
table = document.add_table(rows=1, cols=3)
table.style = 'Light Shading Accent 1'
heading_cells = table.rows[0].cells
heading_cells[0].text = 'Qty'
heading_cells[1].text = 'Item'
heading_cells[2].text = 'Price'

# Add more rows to the table
row_cells = table.add_row().cells
row_cells[0].text = '1'
row_cells[1].text = 'Widget A'
row_cells[2].text = '$10.00'

# Save the document
document.save('my_example.docx')
print("Document 'my_example.docx' created successfully.")

view raw JSON →