docxtpl Skill

Use a .docx file as a Jinja2 template, then fill it with Python data at runtime.

Installation

pip install docxtpl
# For subdocuments support:
pip install "docxtpl[subdoc]"

Quick Start

from docxtpl import DocxTemplate

doc = DocxTemplate("my_template.docx")
context = {"name": "Alice", "department": "Cardiology"}
doc.render(context)
doc.save("output.docx")

Workflow:

1. Design a .docx in Word with Jinja2 tags ({{ var }}, {%p if ... %})
2. Load the template with DocxTemplate(path)
3. Build a Python context dict
4. Call doc.render(context) then doc.save(path)

Tag Reference

Important: Always put spaces around delimiters: {{ var }} not {{var}}.

CLI Usage

python -m docxtpl template.docx data.json output.docx
python -m docxtpl -o template.docx data.json output.docx  # overwrite

Key Classes

• DocxTemplate(path) — Load a .docx template. Methods: .render(context), .save(path), .get_undeclared_template_variables(context=None)
• RichText(text, ...) / R(text) — Styled text with .add() for multi-style concatenation
• InlineImage(tpl, img_path, width, height) — Dynamic image insertion (use Mm(), Inches(), or Pt() for dimensions)
• Listing(text) — Escaped text preserving \ /\a/\f without losing style
• RichTextParagraph() / RP() — Paragraph-level properties (use with {{p var }})
• Subdoc — tpl.new_subdoc(path) to merge existing .docx files

Media Replacement

For headers/footers where dynamic tags aren't supported:

tpl.replace_pic("dummy.jpg", "real.jpg")      # pictures
tpl.replace_media("dummy.mp3", "real.mp3")     # any media
tpl.replace_embedded("dummy.docx", "real.docx") # embedded docs
tpl.replace_zipname("path/in/zip.xlsx", "real.xlsx") # raw zip entry

Escaping

By default, no auto-escaping. Use one of:

• RichText for safe content
• {{ var|e }} in template
• escape("text") in Python context
• tpl.render(context, autoescape=True)

Tips

• \ → newline, \a → new paragraph, → tab, \f → page break (in strings and RichText)
• To render a template multiple times, call tpl.reset_replacements() before each render() if using media replacements
• Pass a custom jinja_env to render() for custom Jinja2 filters
• Preview get_undeclared_template_variables() to warn about missing keys

📖 Full API reference: references/official-docs.md

CLI Scripts

Convenience scripts in scripts/ (use {baseDir}/scripts/ path):

# Render with inline key=value pairs
python scripts/docxtpl-render.py template.docx out.docx name="Alice" age="30"

# Render from JSON file
python scripts/docxtpl-render-json.py template.docx data.json out.docx

# Render from JSON string
python scripts/docxtpl-render.py template.docx out.docx --json '{"name":"Bob"}'

# List missing template variables
python scripts/docxtpl-list-vars.py template.docx

# Batch render from CSV (one .docx per row, named by id column)
python scripts/docxtpl-render-batch.py patients.csv ./reports/ template.docx \
  --id-column patient_id --suffix _report --summary