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.
pip install docxtplVerified import paths — ran on the pinned version, not inferred.
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 }}`.
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.
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.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.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).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 the package using pip: `pip install docxtpl` or `pip3 install docxtpl`. If using a virtual environment, ensure it is activated before installation.
Ensure that `doc.get_docx()` or `doc.render(context)` has been called before trying to access attributes of the `doc` object that rely on the loaded `python-docx` document. For example, call `doc.get_docx()` explicitly if you need to inspect document properties before rendering.
Carefully inspect the Jinja2 tags in your `.docx` template for typos, missing or extra curly braces/percent signs, or other unexpected characters. Retyping the tags directly into Word, ensuring they are correctly delimited, and checking Word's hidden formatting can often resolve this. Ensure complex tags like `{%p %}` are on their own line.Review how images are embedded using `docxtpl.InlineImage`, ensuring image paths are correct and that if the same image is used multiple times, `docxtpl` is allowed to generate unique IDs if necessary. Sometimes, opening the *template* document in Word and re-saving it, or saving it as an RTF file and then back to DOCX, can clean up hidden issues that cause problems during `docxtpl` processing.
Ensure that `{%tr for item in my_list %}` and `{% endtr %}` (or `{%tc %}`/`{% endtc %}`) tags are correctly placed as the sole content within the table cells that define the repeating row or column. Access elements within the loop using the correct dictionary key or attribute, e.g., `{{ item.parameter }}` if `item` is a dictionary.