Create, read, and update Microsoft Word .docx files.
npx @tessl/cli install tessl/pypi-python-docx@1.2.0A comprehensive Python library for creating, reading, and updating Microsoft Word 2007+ (.docx) files. Python-docx provides a high-level API for document manipulation including paragraph creation, text formatting, table management, and image insertion without requiring Microsoft Word to be installed.
pip install python-docxfrom docx import DocumentFor specific components:
from docx import Document
from docx.shared import Inches, Cm, Mm, Pt, Emu, RGBColor
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT, WD_BREAK_TYPE
from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENTfrom docx import Document
from docx.shared import Inches
# Create a new document
doc = Document()
# Add a heading
doc.add_heading('Document Title', 0)
# Add a paragraph
p = doc.add_paragraph('This is a paragraph with some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True
# Add a table
table = doc.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Name'
hdr_cells[1].text = 'Age'
hdr_cells[2].text = 'City'
# Add data to table
row_cells = table.add_row().cells
row_cells[0].text = 'John Doe'
row_cells[1].text = '30'
row_cells[2].text = 'New York'
# Add an image
doc.add_picture('image.png', width=Inches(1.25))
# Save the document
doc.save('demo.docx')Python-docx follows a hierarchical document model based on the Office Open XML format:
The library abstracts the complexity of the underlying XML structure while providing full access to document manipulation capabilities through an intuitive object-oriented interface.
Core document creation, opening, and management functionality including document properties, sections, and saving.
def Document(docx=None):
"""Create or open a Word document.
Args:
docx (str or file-like, optional): Path to .docx file or file-like object
Returns:
Document: Document object for manipulation
"""
class Document:
def save(self, path_or_stream):
"""Save document to file or stream."""
def add_section(self, start_type=WD_SECTION_START.NEW_PAGE):
"""Add a new section to the document."""
@property
def core_properties(self):
"""Core document properties (title, author, etc.)."""Text manipulation including paragraphs, runs, character formatting, and text alignment. Handles rich text formatting with fonts, colors, and styling.
class Document:
def add_paragraph(self, text='', style=None):
"""Add a paragraph to the document."""
def add_heading(self, text='', level=1):
"""Add a heading paragraph."""
class Paragraph:
def add_run(self, text=None, style=None):
"""Add a run of text to the paragraph."""
def clear(self):
"""Remove all content from paragraph."""
@property
def text(self):
"""Plain text content of paragraph."""
class Run:
@property
def font(self):
"""Font formatting object."""
@property
def bold(self):
"""Get/set bold formatting."""Comprehensive table creation and manipulation including rows, columns, cells, and table formatting with merge capabilities.
class Document:
def add_table(self, rows, cols, style=None):
"""Add a table to the document."""
class Table:
def add_row(self):
"""Add a row to the table."""
def add_column(self, width):
"""Add a column to the table."""
def cell(self, row_idx, col_idx):
"""Access specific table cell."""
@property
def rows(self):
"""Collection of table rows."""
@property
def columns(self):
"""Collection of table columns."""Style management and formatting including paragraph styles, character styles, fonts, colors, and measurements.
class Document:
@property
def styles(self):
"""Document styles collection."""
class Font:
@property
def name(self):
"""Font name."""
@property
def size(self):
"""Font size in points."""
@property
def color(self):
"""Font color."""
class ParagraphFormat:
@property
def alignment(self):
"""Paragraph alignment."""
@property
def line_spacing(self):
"""Line spacing."""Image insertion and inline shape management with sizing and positioning controls.
class Document:
def add_picture(self, image_path_or_stream, width=None, height=None):
"""Add an image to the document."""
@property
def inline_shapes(self):
"""Collection of inline shapes in document."""
class InlineShape:
@property
def width(self):
"""Shape width."""
@property
def height(self):
"""Shape height."""Page setup, margins, orientation, headers, footers, and section management for document layout control.
class Section:
@property
def page_width(self):
"""Page width."""
@property
def page_height(self):
"""Page height."""
@property
def orientation(self):
"""Page orientation (portrait/landscape)."""
@property
def header(self):
"""Section header."""
@property
def footer(self):
"""Section footer."""Document commenting system for adding and managing comments anchored to text ranges.
class Document:
def add_comment(self, runs, text='', author='', initials=''):
"""Add a comment to the document.
Args:
runs (Run or list[Run]): Run or sequence of runs to anchor comment to
text (str, optional): Comment text content
author (str, optional): Comment author name
initials (str, optional): Author initials
Returns:
Comment: New comment object
"""
@property
def comments(self):
"""Collection of document comments."""
class Comment:
@property
def text(self):
"""Comment text content."""
@property
def author(self):
"""Comment author."""class Length(int):
"""Base measurement class in English Metric Units."""
@property
def inches(self):
"""Value in inches."""
@property
def cm(self):
"""Value in centimeters."""
def Inches(inches):
"""Create Length object from inches."""
def Cm(cm):
"""Create Length object from centimeters."""
def Mm(mm):
"""Create Length object from millimeters."""
def Pt(points):
"""Create Length object from points."""
class RGBColor(tuple):
"""RGB color specification."""
def __init__(self, r, g, b):
"""Create RGB color from 0-255 values."""Key enumeration values for document formatting:
from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
# Values: LEFT, CENTER, RIGHT, JUSTIFY, DISTRIBUTE
from docx.enum.text import WD_BREAK_TYPE
# Values: COLUMN, LINE, PAGE, TEXT_WRAPPING
from docx.enum.table import WD_TABLE_ALIGNMENT
# Values: LEFT, CENTER, RIGHT
from docx.enum.section import WD_ORIENTATION
# Values: PORTRAIT, LANDSCAPE