---
source: https://iinventedlight.com/library/notes/hf-chat-templates.md
title: "Chat templates in Hugging Face Transformers"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "Apache-2.0 (huggingface docs repos); prose restates cited source lines"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Hugging Face docs, Chat templates · Hugging Face, Apache-2.0 (huggingface docs repos); Hugging Face docs, Chat basics · Hugging Face, Apache-2.0 (huggingface docs repos)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: Hugging Face"
tags: ['hugging-face', 'transformers', 'chat-models', 'tokenizers']
sources:
  - id: S1
    title: "Chat templates · Hugging Face"
    publisher: Hugging Face docs
    url: https://huggingface.co/docs/transformers/chat_templating
    accessed: 2026-11-04
    license: "Apache-2.0 (huggingface docs repos)"
  - id: S2
    title: "Chat basics · Hugging Face"
    publisher: Hugging Face docs
    url: https://huggingface.co/docs/transformers/conversations
    accessed: 2026-11-04
    license: "Apache-2.0 (huggingface docs repos)"
---
# Chat templates in Hugging Face Transformers

**Answer:** A chat template turns a list of `{role, content}` messages into the exact token sequence a chat model was trained on, including control tokens.

```python
from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained("HuggingFaceH4/zephyr-7b-beta")

messages = [
    {"role": "system", "content": "You are a helpful science assistant."},
    {"role": "user", "content": "Why is the sky blue?"},
]
text = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
ids = tok.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt")
```

## Key points

- Messages are dictionaries with role and content keys; common roles are system, user and assistant.
- `add_generation_prompt=True` appends the marker for the assistant's turn so the model answers rather than continuing the user message.
- Two models fine-tuned from the same base can still use different templates.

## Pipelines


```python
from transformers import pipeline
chat = pipeline("text-generation", model="HuggingFaceH4/zephyr-7b-beta")
chat(messages, max_new_tokens=128)
```

## Claims
- id: C1
  claim: Chats are converted to token sequences, often with control tokens.
  source: S1
  evidence: "to a chat model get converted to a token sequence, often with control tokens like"
- id: C2
  claim: apply_chat_template input is a list of dictionaries with role and content keys.
  source: S1
  evidence: "The input to apply_chat_template should be structured as a list of dictionaries with role"
- id: C3
  claim: Chat models accept a list of messages as input.
  source: S2
  evidence: "Chat models accept a list of messages (the chat history) as the input."
- id: C4
  claim: You can include a system message to direct behavior.
  source: S2
  evidence: "You can also optionally include a system message to give the model directions"

## Sources
- [S1] Chat templates · Hugging Face. Hugging Face docs. https://huggingface.co/docs/transformers/chat_templating . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-04.
- [S2] Chat basics · Hugging Face. Hugging Face docs. https://huggingface.co/docs/transformers/conversations . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).