A chat template is a Jinja file that ships with many models and turns your list of messages into the exact text the model reads. It is third party text and logic you did not write, so read it, pin its version and diff it whenever you update the model.
What a chat template is
According to the Hugging Face Transformers documentation, a chat template is a Jinja template stored in the tokenizer's chat template attribute. It loops over the messages, adds role markers and special tokens, and can add a start of reply header. It is saved with the tokenizer and applied whenever the application calls the chat template function.
In other words, between your code and the model sits a small program written by someone else. It decides where the system message goes, how tool definitions are rendered and what separators the model sees.
Where it lives
The documentation describes several storage forms.
- A standalone file named chat_template.jinja at the repository root, which is the recommended form.
- A directory of additional named templates, for models that ship more than one, such as a separate tool use template.
- Older repositories that embed the template as a string in the tokenizer configuration or a separate JSON file, kept for loading, not for writing.
When more than one form is present, the loader applies a fixed precedence, and a standalone Jinja file overrides the embedded field. That means a repository can contain more than one template and the one that wins depends on rules most people never read. Print the final template your code actually uses.
Why it deserves review
The template is part of your prompt, so it can affect behavior.
- It can insert text you did not expect, such as a default system message or a date.
- It controls how untrusted message content is placed relative to instructions.
- It is editable by whoever can change the repository, and a changed template alters every conversation.
- It runs inside your process when rendered, so how it is rendered matters.
The documentation notes that templates can call a small set of functions, such as raising an exception or fetching the current time, and can read any extra keyword arguments you pass in. That is limited, but it is still code. Render templates from untrusted sources with a sandboxed Jinja environment, and read the Jinja sandbox notes on resource use and limiting the data you pass.
A short review routine
- Print the template your application resolves, not the one you assume.
- Read it end to end. Most are under a hundred lines for plain chat models, and longer for tool use models.
- Look for hard coded text, unusual special tokens and anything that reads data you did not intend to pass.
- Save a copy in your repository, with a hash and the model revision it came from.
- Diff the template whenever you change the model version.
- Compare the rendered text with the format the model card describes. A mismatch can quietly hurt quality.
Pin and track it
Record the template alongside the model revision in your model inventory. If the model repository can change under a floating reference, pin to a specific revision so a template edit cannot reach production unnoticed. For the pinning method, see pin a Hugging Face model revision to a commit hash.
Quick check
Is a chat template a security risk by itself?
Not usually, but it is unreviewed text and logic that shapes every prompt. Treat it as a dependency you inspect and pin.
Do I need to review templates for models I call through an API?
Usually the provider applies the template server side, so you cannot inspect it. This matters for models you download and run yourself.
Sources
Last reviewed: 19 October 2026.
