docxtpl-lint

中文文档 / Chinese

A static linter for docxtpl (python-docx-template) Word templates. It points each problem to the exact table cell, reports all problems in one run, and returns exit codes your CI can use.

▶ Try it in your browser: drop a .docx and see the report. The file never leaves your computer; the linter runs locally via Pyodide.

docxtpl itself only gives you this, with no location and only the first error:

jinja2.exceptions.TemplateSyntaxError: Encountered unknown tag 'endfor'. Jinja was looking for the following tags: 'elif' or 'else' or 'endif'.

Not affiliated with python-docx-template. Tested against docxtpl 0.20.2 and checked weekly against docxtpl's latest release and master.

Benchmark: docxtpl's own templates

The 40 templates in python-docx-template's tests/templates are written by the docxtpl maintainers and render correctly, except template_error_tpl.docx, which is broken on purpose. CI lints all of them every week (scripts/benchmark.py, benchmark/expected.json):

All 40 templates are linted in about 0.1 s. Since 1.0 the benchmark also runs verify (infer sample data, then render with the real docxtpl): 37 of 40 templates render with inferred data alone, with 0 false DTL401. The other three are the deliberately broken template and two that need Python objects (a custom Jinja filter, a function passed in the context).

Tested adversarially (1.1)

DeepSeek designed 86 adversarial templates from the docs (cases). Each was built as a real .docx and also rendered with docxtpl to decide disputes. The first run found 5 real problems, all fixed in 1.1: }} inside a string literal, unclosed {% raw %}, comments counted as lost text, text in other cells of a {%tr %} row, and noisy DTL209 next to errors. Now all 86 cases match the adjudicated expectations in CI. Reports: DeepSeek's evaluation, self-evaluation.

New in 1.8: CI ecosystem

• The GitHub Action writes a Markdown table to the job summary. New inputs: baseline, sarif: docxtpl-lint.sarif (for github/codeql-action/upload-sarif), and annotate: true (failing templates with Word comments, uploaded as an artifact).
• --format gitlab for GitLab Code Quality; --format markdown; --report FORMAT:FILE to write several reports in one run. Findings carry stable fingerprints, so CI tools can track them across commits.

New in 1.7: fix --write

docxtpl-lint fix contract.docx --write contract.fixed.docx applies the safe fixes (missing }, {% tr → {%tr, prefix pairs, misspelt endfro) to a copy, editing inside the existing Word runs so formatting is kept. Guesses (e.g. renaming custmer after --data) need --unsafe. The original template is never touched.

New in 1.6: escaping and a stronger verify

• DTL308 (with --data): docxtpl renders with autoescape=False by default, so Smith & Co becomes Smith Co and <b> cuts the paragraph, with no error. Use render(ctx, autoescape=True) (and --autoescape) or {{ name|e }}.
• verify now renders the way your code does (--jinja-env, --autoescape, several --data files), checks {{r}} / {{p}} too, and can keep the output with --out DIR.

New in 1.5: a more precise data contract

• List and attribute filters feed the contract: items|sum(attribute='price') makes items[].price a number, and loops over items|selectattr('ok') keep the item fields.
• DTL306 (with --data): tags|join(", ") on a string silently prints u, r, g, e, n, t; on a number it raises.
• DTL307 (with --data): {{r note }} with a plain string renders nothing. The schema and Pydantic models mark such fields as RichText / Subdoc.

New in 1.4: tracked changes and field codes

• DTL003: an unaccepted tracked deletion that still contains {{ … }}. docxtpl renders deleted text too, so the value leaks into the revision history of every generated document. Fix: accept or reject all changes first.
• Field codes (HYPERLINK "{{ url }}") are rendered by docxtpl and are now linted and included in the data contract.

New in 1.3: Jinja correctness

• DTL104 / DTL105: unknown filters and tests ({{ total|money }} makes docxtpl raise before rendering). If you pass your own jinja_env, declare the names with --filters money, --tests vat, the filters / tests config keys, or --jinja-env myapp.reports:jinja_env.
• DTL106: a loop variable or a set inside a loop used after the loop. It renders empty or raises; use namespace() instead.

New in 1.2: ideas from other linters

Picked from a survey of 19 projects (docs/research/oss-survey.md, decisions D74–D86):

What's new in 1.0: from linting to data contracts

Five things no other docxtpl tool does (see docs/PLAN-v1.0.md for the reasoning):

verify found a docxtpl behaviour that no rule covered: text next to a {%p %}, {%tr %} or {%tc %} tag is dropped from the output without an error. That is now the static rule DTL209. The playground shows the fix suggestions and the inferred schema/sample data too.

$ docxtpl-lint verify invoice.docx
invoice.docx:body ¶1:7: error DTL401 `{{ total }}` was rendered by docxtpl but its value does not appear in the output document
    {{ total }}
      > ¶1             | Total {{ total }} {%p if x %}
        ¶2             | {%p endif %}

Features

• Table-cell locations. Each issue names the part (body, header1, footer2, footnotes), the paragraph, and for tables a path like T1 R2 C2 > T2 R2 C1 (table, row, column; nested tables supported). The offending tag text is always printed.
• All block problems in one run. Unclosed if/for, stray endfor/else, and tags that never close are found with the linter's own tag stack, so you don't fix-render-repeat. Other Jinja syntax errors are reported once per document part, as Jinja itself does.
• Knows docxtpl's own tags. {%tr %}, {%tc %}, {%p %}, {%r %}. Each docxtpl rule has a test that renders a bad template with the real docxtpl and checks that it really breaks.
• Checks templates against sample data. --data sample.json checks every variable path, including nested fields and loop items such as items[*].price. Paths guarded with is defined or | default(...) are not reported.
• Built for CI. Exit codes, --format json|github|sarif, a GitHub Action and a pre-commit hook.
• Read-only. Your .docx is never modified. The linter reads the OOXML with lxml and does not import docxtpl (only verify does, through the optional [render] extra).

Install

Install from PyPI:

pip install docxtpl-lint
pip install "docxtpl-lint[render]"   # + verify

Usage

docxtpl-lint templates/*.docx
docxtpl-lint contract.docx --data sample.json            # + data checks (repeat --data for several contexts)
docxtpl-lint contract.docx --format json > report.json   # machine readable (schema_version: 1)
docxtpl-lint contract.docx --list-vars                   # which data does this template need?
docxtpl-lint contract.docx --lang zh                     # 中文提示
docxtpl-lint contract.docx --context 2                   # show 2 paragraphs around each issue
docxtpl-lint --list-rules
docxtpl-lint --explain DTL209                           # what a rule means, with a link to examples
docxtpl-lint infer contract.docx -o schema.json --sample sample.json
docxtpl-lint contract.docx --schema schema.json           # DTL304/305
docxtpl-lint verify contract.docx                        # needs docxtpl-lint[render]
docxtpl-lint diff v1/contract.docx v2/contract.docx --fail-on-breaking
docxtpl-lint fix contract.docx [--data sample.json]      # prints diffs
docxtpl-lint fix contract.docx --write fixed.docx         # apply safe fixes to a copy
docxtpl-lint templates/*.docx --statistics               # count per rule
docxtpl-lint templates/*.docx --write-baseline bl.json   # accept today's findings ...
docxtpl-lint templates/*.docx --baseline bl.json         # ... and fail only on new ones
docxtpl-lint templates/*.docx --annotate review/         # copies with Word comments
docxtpl-lint infer contract.docx --pydantic models.py    # Pydantic v2 models

Other options: --select DTL1,DTL206, --ignore DTL2 (prefix match), --allow-cross-paragraph, --report-unused-data, --warnings-as-errors, --no-color.

--context N prints the surrounding paragraphs with their table position, so you can find the spot without opening Word. It defaults to 1 in a terminal and 0 in CI logs and pipes.

Configuration

Put defaults in the nearest pyproject.toml. Command-line options take precedence, and unknown keys are an error (exit 2):

[tool.docxtpl-lint]
ignore = ["DTL002"]
data = ["tests/sample_context.json"]  # relative to this pyproject.toml
warnings-as-errors = true
lang = "en"                           # or "zh"
# also: select, allow-cross-paragraph, report-unused-data, context, baseline, filters, tests, jinja-env, autoescape

Use --config path/to/pyproject.toml to pick a file, or --no-config to ignore it.

To silence rules for one template, put a Jinja comment anywhere in it (docxtpl renders it as nothing): {# docxtpl-lint: disable=DTL301,DTL002 #}. For one paragraph use disable-line= / disable-next= (see docs/rules.md); a suppression that matches nothing is reported as DTL005.

Rules

Each rule has examples and a fix in docs/rules.md. JSON and SARIF output link to the matching entry.

Upstream issues → rules

Use in CI

GitHub Action (annotations appear on the run and in the PR):

- uses: actions/checkout@v7
- uses: yq6666-66/docxtpl-lint@v1.8.0
  with:
    files: |
      templates/**/*.docx
    args: --data tests/sample_context.json
    # baseline: docxtpl-lint-baseline.json
    # sarif: docxtpl-lint.sarif
    # annotate: true

pre-commit

repos:
  - repo: https://github.com/yq6666-66/docxtpl-lint
    rev: v1.8.0
    hooks:
      - id: docxtpl-lint
        # args: [--data, tests/sample_context.json]

GitLab CI (Code Quality report):

docxtpl-lint:
  image: python:3.12
  script:
    - pip install docxtpl-lint
    - docxtpl-lint --format gitlab -o gl-code-quality.json templates/*.docx
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality.json

Plain shell: docxtpl-lint --format github templates/*.docx

reviewdog (reads SARIF, can post PR review comments):

docxtpl-lint --format sarif templates/*.docx | reviewdog -f=sarif -name=docxtpl-lint -reporter=github-pr-review

What it does not check

• Runtime errors: unknown filters, wrong types, failing include, macro signature mismatches, custom jinja_env extensions. The linter assumes docxtpl's default jinja2.Environment().
• Parts docxtpl does not render: endnotes, comments, charts, embedded objects. Text boxes are checked as part of their paragraph.
• ¶N counts every <w:p> of the part, including empty paragraphs inside table cells. Use the table path and the printed snippet to find the spot in Word.
• DTL201 follows the regex of docxtpl ≤ 0.20.2. If upstream relaxes it (open PR #645), use --ignore DTL201.

Related

lintxtpl by splittist was the first linter for docxtpl templates and can write an annotated .docx with Word comments (docxtpl-lint 1.2 adopted that idea as --annotate). docxtpl-lint focuses on table-cell locations, docxtpl-specific rules and checks against sample data.

Contributing

See CONTRIBUTING.md. Every new docxtpl rule needs a case in tests/rule_cases.py that renders with the real docxtpl.

License

MIT