docx

name: docx description: Word document processing — reading, creating with python-docx, editing via XML manipulation, styles, tables, images, headers/footers, tracked changes.

Word Document (DOCX) Processing

When the user needs to read, create, or edit Word documents, follow this guide.

1. Reading DOCX files

Quick text extraction

Use the read tool directly — it natively extracts text from DOCX files:

read(file_path="report.docx")

Returns paragraphs (with heading markers) and tables in Markdown-like format.

Detailed access

For more control (styles, formatting, images), use python-docx via a Python script:

from docx import Document

doc = Document("report.docx")

# Paragraphs with style info
for para in doc.paragraphs:
    print(f"[{para.style.name}] {para.text}")

# Tables
for table in doc.tables:
    for row in table.rows:
        print([cell.text for cell in row.cells])

# Document properties
props = doc.core_properties
print(f"Author: {props.author}")
print(f"Created: {props.created}")

2. Creating DOCX files

Basic document

from docx import Document
from docx.shared import Inches, Pt, Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

# Title
doc.add_heading("Document Title", level=0)

# Paragraph with formatting
para = doc.add_paragraph()
run = para.add_run("Bold text")
run.bold = True
para.add_run(" and ")
run2 = para.add_run("italic text")
run2.italic = True

# Normal paragraph
doc.add_paragraph("This is a normal paragraph.")

# Bullet list
doc.add_paragraph("First item", style="List Bullet")
doc.add_paragraph("Second item", style="List Bullet")

# Numbered list
doc.add_paragraph("Step one", style="List Number")
doc.add_paragraph("Step two", style="List Number")

doc.save("output.docx")

Tables

from docx import Document
from docx.shared import Cm
from docx.oxml.ns import qn

doc = Document()

# Create table
table = doc.add_table(rows=3, cols=3, style="Table Grid")

# Set header row
headers = ["Name", "Department", "Salary"]
for i, header in enumerate(headers):
    cell = table.rows[0].cells[i]
    cell.text = header
    # Bold header
    for para in cell.paragraphs:
        for run in para.runs:
            run.bold = True

# Fill data
data = [
    ["Alice", "Engineering", "$120,000"],
    ["Bob", "Marketing", "$95,000"],
]
for row_idx, row_data in enumerate(data, 1):
    for col_idx, value in enumerate(row_data):
        table.rows[row_idx].cells[col_idx].text = value

# Set column widths
for row in table.rows:
    row.cells[0].width = Cm(4)
    row.cells[1].width = Cm(4)
    row.cells[2].width = Cm(3)

doc.save("table.docx")

Images

from docx import Document
from docx.shared import Inches

doc = Document()
doc.add_heading("Report with Image", level=1)
doc.add_picture("chart.png", width=Inches(5))
doc.add_paragraph("Figure 1: Quarterly results")
doc.save("report.docx")

Headers and footers

from docx import Document

doc = Document()

# Header
section = doc.sections[0]
header = section.header
header.paragraphs[0].text = "Company Name — Confidential"

# Footer with page number
footer = section.footer
footer.paragraphs[0].text = "Page "
# Page number requires XML manipulation for auto-numbering

doc.save("with_header.docx")

Page setup

from docx import Document
from docx.shared import Cm, Inches
from docx.enum.section import WD_ORIENT

doc = Document()
section = doc.sections[0]

# Page size (A4)
section.page_width = Cm(21)
section.page_height = Cm(29.7)

# Margins
section.top_margin = Cm(2.54)
section.bottom_margin = Cm(2.54)
section.left_margin = Cm(3.17)
section.right_margin = Cm(3.17)

# Landscape orientation
section.orientation = WD_ORIENT.LANDSCAPE
# Swap width/height for landscape
section.page_width, section.page_height = section.page_height, section.page_width

3. Editing existing DOCX files

Simple modifications with python-docx

from docx import Document

doc = Document("existing.docx")

# Modify paragraph text
for para in doc.paragraphs:
    if "old text" in para.text:
        for run in para.runs:
            run.text = run.text.replace("old text", "new text")

doc.save("modified.docx")

XML-level editing (advanced)

DOCX files are ZIP archives containing XML. For complex edits:

1. Unpack: Extract the ZIP to access XML files
2. Edit: Modify the XML directly
3. Repack: Zip the files back into a .docx

import zipfile
import os
import shutil

def unpack_docx(docx_path, output_dir):
    """Extract DOCX to a directory."""
    with zipfile.ZipFile(docx_path, "r") as z:
        z.extractall(output_dir)

def pack_docx(input_dir, docx_path):
    """Repackage directory into DOCX."""
    with zipfile.ZipFile(docx_path, "w", zipfile.ZIP_DEFLATED) as z:
        for root, dirs, files in os.walk(input_dir):
            for file in files:
                file_path = os.path.join(root, file)
                arcname = os.path.relpath(file_path, input_dir)
                z.write(file_path, arcname)

# Usage
unpack_docx("document.docx", "unpacked/")
# Edit unpacked/word/document.xml
pack_docx("unpacked/", "modified.docx")

Key XML files in a DOCX

XML namespace

DOCX XML uses the WordprocessingML namespace:

<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  <w:body>
    <w:p>              <!-- paragraph -->
      <w:pPr>          <!-- paragraph properties -->
        <w:pStyle w:val="Heading1"/>
      </w:pPr>
      <w:r>            <!-- run -->
        <w:rPr>        <!-- run properties -->
          <w:b/>       <!-- bold -->
        </w:rPr>
        <w:t>Text</w:t>
      </w:r>
    </w:p>
  </w:body>
</w:document>

4. Styles reference

Built-in styles

Custom font and size

from docx.shared import Pt, RGBColor

run = para.add_run("Custom text")
run.font.name = "Arial"
run.font.size = Pt(14)
run.font.color.rgb = RGBColor(0x42, 0x24, 0xE9)
run.font.bold = True
run.font.italic = True
run.font.underline = True

CJK (Chinese/Japanese/Korean) font support

IMPORTANT: run.font.name only sets the Western font (w:ascii/w:hAnsi). CJK characters require the East Asian font (w:eastAsia) to be set via XML, otherwise they render as □ (empty boxes) in Word.

Always use this helper when the document contains CJK text:

from docx.oxml.ns import qn

def set_run_font(run, western_font="Arial", east_asia_font="Microsoft YaHei", size_pt=None):
    """Set both Western and East Asian fonts on a run."""
    run.font.name = western_font
    # Set East Asian font via XML (required for CJK characters)
    r_element = run._element
    rPr = r_element.get_or_add_rPr()
    rFonts = rPr.find(qn('w:rFonts'))
    if rFonts is None:
        from docx.oxml import OxmlElement
        rFonts = OxmlElement('w:rFonts')
        rPr.insert(0, rFonts)
    rFonts.set(qn('w:eastAsia'), east_asia_font)
    if size_pt:
        from docx.shared import Pt
        run.font.size = Pt(size_pt)

# Usage
run = para.add_run("中文文本 English text")
set_run_font(run, "Arial", "Microsoft YaHei", size_pt=12)

Common East Asian fonts:

Setting CJK font on default document style (applies to all new text):

from docx.oxml.ns import qn

doc = Document()
style = doc.styles['Normal']
style.font.name = 'Arial'
style.element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')

5. Dependencies

Core (included with Muse):

• python-docx — read, create, basic editing

No additional optional dependencies required for most tasks.