docxtpl Skill#

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

Installation#

bash

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

Quick Start#

python

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#

TagScopePurpose{{ var }}inline stringDisplay a variable{{r var }}inline styledDisplay a RichText object{%p ... %}paragraphControl full paragraphs (if/for){%tr ... %}table rowControl table rows{%tc ... %}table columnControl table columns{%r ... %}runControl styled runs{%p if cond %} / {%p endif %}paragraphConditional paragraph{%p for x in list %} / {%p endfor %}paragraphLoop over paragraphs{% colspan N %}table cellHorizontal cell spanning{% hm %}table cellHorizontal merge in for-loop{% vm %}table cellVertical merge in for-loop{% cellbg color %}table cellSet cell background color{ #p comment #}paragraphComment{%- -%}text mergeMerge split lines{ _%, %_ }, { _{, }_ }escapeDisplay literal {%, %}, {{, }}

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

CLI Usage#

bash

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 \n/ \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:

python

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#

• \n → newline, \a → new paragraph, \t → 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):

bash

# 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