docxtpl

0.20.2 · active · verified Sat Apr 11

docxtpl is a Python library that serves as a docx template engine, enabling the generation of Word documents from templates enhanced with Jinja2-like tags. It leverages `python-docx` for document manipulation and `jinja2` for templating logic. The current version is 0.20.2, and it appears to be actively maintained with regular updates.

Warnings

gotcha Jinja2 tag placement is crucial. Standard `{{ }}` tags must reside within a single 'run' of text in a paragraph. For controlling entire paragraphs, table rows, or cells, special tags like `{%p ... %}`, `{%tr ... %}`, `{%tc ... %}` respectively are required. Incorrect placement often leads to unexpected rendering or content being crammed.
Fix: Use the appropriate `p`, `tr`, `tc`, or `r` prefixed tags for structural control (paragraph, table row, table cell, run). Consult the official documentation for examples on splitting long text or table loops with these tags.
gotcha RichText objects are not compatible with Jinja2 filters directly within the template. If you need to apply formatting or transformations to `RichText` content, perform these operations in your Python code *before* passing the `RichText` object to the template context.
Fix: Pre-process `RichText` content in Python. For example, `context = {'my_text': RichText(my_raw_text.lower())}` instead of `{{r my_text|lower }}` in the template.
gotcha When working with loops in tables (`{%tr for item in items %}`), ensure the loop tags correctly span the cells of the row you intend to duplicate. Incorrect placement can cause all iterated data to appear in a single cell instead of generating new rows.
Fix: Place the `{%tr for ... %}` tag in the first cell of the row to be repeated and the `{%tr endfor %}` tag in the last cell of that same row. The documentation provides examples for proper table looping.
gotcha Controlling whitespace when using conditional or loop tags can be tricky. Unwanted spaces might appear if not handled correctly.
Fix: Use Jinja2's whitespace control characters `{%-` and `-%}` to strip whitespace around blocks. For explicit spaces at line beginnings or endings in the Word document, use an unbreakable space (Ctrl+Shift+Space in Microsoft Word).
breaking Prior to version 0.15.1, calling `render()` multiple times on the same `DocxTemplate` object could lead to loss of unresolved variables, making multi-step rendering problematic.
Fix: Upgrade to `docxtpl` version 0.15.1 or newer to enable reliable multi-rendering with a single `DocxTemplate` object. If upgrading is not possible, ensure all context is provided in a single `render()` call.

Install

pip install docxtpl PyPI
conda install docxtpl --channel conda-forge Conda-forge

Imports

DocxTemplate
```
from docxtpl import DocxTemplate
```
InlineImage
```
from docxtpl import InlineImage
```
RichText
```
from docxtpl import RichText
```
Can also be imported as 'R'.
RichTextParagraph
```
from docxtpl import RichTextParagraph
```
Can also be imported as 'RP'.
Mm
```
from docx.shared import Mm
```
Used for specifying dimensions (e.g., image width/height). Also 'Inches' and 'Pt' are available.

Quickstart

This quickstart demonstrates how to load a .docx template, provide a dictionary of context variables, render the template, and save the generated document. The template itself would be a standard .docx file created in Microsoft Word, containing Jinja2-like placeholders such as `{{ variable_name }}`.

import os
from docxtpl import DocxTemplate

# Create a dummy template file for demonstration
dummy_template_content = (
    "Hello {{ name }},\n"
    "This is a test document generated by docxtpl.\n"
    "Your company: {{ company_name }}.\n"
)
with open("my_word_template.docx", "w") as f:
    # In a real scenario, this would be a proper .docx file with Jinja2 tags
    # For a runnable quickstart, we'll simulate a simple text file
    f.write(dummy_template_content)

# Path to your Word template file (e.g., 'my_word_template.docx')
template_path = "my_word_template.docx"
output_path = "generated_doc.docx"

# Ensure the template file exists (in a real scenario, it's a pre-made .docx)
if not os.path.exists(template_path):
    # For a real .docx, you would create it in MS Word
    print(f"Please create a real .docx template named '{template_path}' with {{ name }} and {{ company_name }} tags.")
    # Exit or handle error if the template doesn't exist
    exit(1)

# Load the template
doc = DocxTemplate(template_path)

# Define the context (data to fill into the template)
context = {
    'name': 'World',
    'company_name': 'Example Inc.'
}

# Render the document with the context
doc.render(context)

# Save the generated document
doc.save(output_path)

print(f"Generated document saved to {output_path}")

# Clean up the dummy file (optional)
# os.remove(template_path)
# os.remove(output_path)

view raw JSON →