python-docx
Python library for creating and modifying Microsoft Word .docx files — generates structured Word documents programmatically. python-docx features: Document class (new or existing), add_paragraph() and add_heading(), add_run() for inline text with formatting (bold, italic, font size, color), add_table() with cell access, add_picture() for inline images, styles (Heading 1, Normal, Quote), paragraph formatting (alignment, indentation, spacing), section page setup (landscape, margins), add_page_break(), list styles (bulleted, numbered), hyperlinks via XML, and core properties (author, title). Standard library for generating Word document reports from agent data.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Local file generation — no network access. .docx files are ZIP archives of XML — validate source before opening untrusted documents. Macros (.docm) not supported. Agent template filling must sanitize user input to prevent XML injection in document content.
⚡ Reliability
Best When
Generating Word document reports for business users who need to edit or add to agent output — python-docx creates editable Word files with proper structure, styles, and tables that business stakeholders can work with in Microsoft Word.
Avoid When
You need PDF output (use reportlab/weasyprint), complex page layouts, or legacy .doc format support.
Use Cases
- • Agent document generation — doc = Document(); doc.add_heading('Agent Report', 0); doc.add_paragraph(f'Generated: {datetime.now()}'); doc.add_heading('Findings', 1); doc.add_paragraph('Critical issues found: ...'); doc.save('report.docx') — generate Word report from agent findings; business-readable output for non-technical stakeholders
- • Agent table report — table = doc.add_table(rows=1, cols=4, style='Table Grid'); table.rows[0].cells[0].text = 'Agent'; for agent in agents: row = table.add_row(); row.cells[0].text = agent.name; row.cells[1].text = agent.status — tabular data in Word; agent risk assessment report with formatted table
- • Agent template filling — doc = Document('template.docx'); for para in doc.paragraphs: if '{{agent_name}}' in para.text: para.text = para.text.replace('{{agent_name}}', agent_name); doc.save('filled.docx') — fill Word template with agent data; document automation for contracts, reports with fixed structure
- • Agent formatted findings — para = doc.add_paragraph(); run = para.add_run('CRITICAL: '); run.bold = True; run.font.color.rgb = RGBColor(255, 0, 0); para.add_run(finding_text) — styled text for agent security report; red bold severity labels inline with body text; professional security finding documentation
- • Agent picture report — doc.add_picture('chart.png', width=Inches(6)) — embed chart image in Word document; agent includes matplotlib/plotly chart screenshots in report; Inches() and Cm() for precise image sizing
Not For
- • PDF generation — python-docx creates .docx only; convert to PDF via LibreOffice headless or docx2pdf; for direct PDF generation use reportlab or weasyprint
- • Complex layout (multi-column, precise positioning) — Word document layout is flow-based; for pixel-precise layouts use PDF libraries
- • Reading .doc (old Word) — python-docx only handles .docx (Word 2007+); for .doc use LibreOffice conversion first
Interface
Authentication
No auth — local document generation library.
Pricing
python-docx is MIT licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ para.text = value clears all run formatting — paragraph.text = 'new text' replaces all runs with single unformatted run; losing bold/italic formatting from template; agent template filling must iterate runs: for run in para.runs: run.text = run.text.replace('{{var}}', value); not para.text = para.text.replace()
- ⚠ Styles must exist in document or template — doc.add_paragraph(style='Custom Style') raises KeyError if 'Custom Style' not in document styles; agent code using custom styles must either define styles or use documents with those styles already defined; use existing built-in styles safely
- ⚠ add_table() requires explicit cell content — table = doc.add_table(rows=3, cols=3); table.cell(0, 0).text = 'Header'; empty table cells display as blank in Word; agent code must explicitly set all cell text; iterating with table.rows and table.columns is reliable for all cells
- ⚠ Images must be on disk — doc.add_picture('path/to/image.png') requires file path; BytesIO works: doc.add_picture(io.BytesIO(img_bytes)); matplotlib agent charts must be saved to disk or BytesIO before embedding; fig.savefig(buf := io.BytesIO()); buf.seek(0); doc.add_picture(buf)
- ⚠ Hyperlinks require XML manipulation — python-docx has no built-in add_hyperlink(); adding hyperlinks requires direct XML manipulation via lxml; agent reports needing clickable links must use workaround: add_hyperlink() XML helper function from python-docx GitHub issues; display text without links if complexity not worth it
- ⚠ Table styles from Word template differ from built-in names — doc.add_table(style='Table Grid') works for built-in; table style from .dotx template has display name not programmatic name; agent code inheriting Word templates must inspect doc.tables[0].style.name to find correct style string
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for python-docx.
Scores are editorial opinions as of 2026-03-06.