Metadata

name: docxtpl
description: Generate Word (.docx) documents from Jinja2 templates. Uses python-docx (read/write) + Jinja2 (template engine). Design templates in Microsoft Word, then populate with Python variables.
version: 0.0.1
homepage: https://docxtpl.readthedocs.io/en/latest/
pip: docxtpl
metadata: {"openclaw":{"requires":{"bins":["python3"]}}}

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:

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

Tag Reference

Tag	Scope	Purpose
`{{ var }}`	inline string	Display a variable
`{{r var }}`	inline styled	Display a `RichText` object
`{%p ... %}`	paragraph	Control full paragraphs (if/for)
`{%tr ... %}`	table row	Control table rows
`{%tc ... %}`	table column	Control table columns
`{%r ... %}`	run	Control styled runs
`{%p if cond %}` / `{%p endif %}`	paragraph	Conditional paragraph
`{%p for x in list %}` / `{%p endfor %}`	paragraph	Loop over paragraphs
`{% colspan N %}`	table cell	Horizontal cell spanning
`{% hm %}`	table cell	Horizontal merge in for-loop
`{% vm %}`	table cell	Vertical merge in for-loop
`{% cellbg color %}`	table cell	Set cell background color
`{ #p comment #}`	paragraph	Comment
`{%- -%}`	text merge	Merge split lines
`{ _%`, `%_ }`, `{ _{`, `}_ }`	escape	Display literal `{%`, `%}`, `{{`, `}}`

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

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):

# 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

Docxtpl

安装技能