In Django's {% include %} tag, what context does the included template see, and how do the with and only options change it?

## What `{% include %}` does `{% include %}` loads another template and renders it in place. On a travel-bookings site it is the usual way to reuse a fragment such as a fare summary or a booking card on several pages: ```django {% for booking in bookings %} {% include 'bookings/_card.html' %} {% endfor %} ``` The template name can be a quoted string, a relative path such as `'./_card.html'`, a variable holding a name, a variable holding a compiled template object, or an iterable of names — in which case the first one that loads is used. From Django 6.0 the name may also point at a single partial inside a file, `'bookings/list.html#booking-row'`. Django's documentation is explicit about the model: `include` means **"render this subtemplate and include the HTML"**, not "parse this subtemplate as if it were part of the parent". Each include is an independent rendering pass. ## The three context modes | Form | What the included template can read | |---|---| | `{% include 'x.html' %}` | the whole current context: view variables, loop variables, context-processor values | | `{% include 'x.html' with a=b %}` | all of the above, plus `a` for this include only | | `{% include 'x.html' with a=b only %}` | only `a` (and the literals `True`, `False`, `None`) | The `with` values are resolved in the includer's context, then pushed onto the context stack while the included template renders and popped afterwards, so they never leak back into the includer. Inside a loop, the default mode means the fragment sees the loop variable and `forloop` directly, which is convenient but couples the fragment to whatever name the caller's loop happened to use. ## `only` removes more than the view's variables `only` builds a fresh context containing just the `with` values. It does **not** re-run context processors, so variables that normally appear on every page — `user`, `request`, `perms`, `messages`, the CSRF token — are all absent inside an `only` include. A fragment that renders a form with `{% csrf_token %}` or checks `user.is_authenticated` silently breaks under `only` unless those values are passed explicitly through `with`. The trade-off: - **Plain include** — easiest to write, but the fragment depends invisibly on names in the caller's scope. - **`with ... only`** — the fragment's inputs are explicit and it behaves the same on every page, at the cost of passing everything it needs, including values you took for granted. ## An include is a render, not a paste Because the included template is rendered independently: 1. **Blocks inside an included file are already rendered.** If `_sidebar.html` defines `{% block promo %}`, a child template that extends the page including it cannot override `promo`; that block is part of finished HTML by the time inheritance sees it. 2. **No state is shared back.** Variables set inside the included template do not appear in the includer. 3. **Errors surface at render time.** A missing included template raises `TemplateDoesNotExist` when the tag renders. Within one render, the include tag caches the compiled template it loaded, so an include inside a loop does not reload the file on every iteration; each iteration is still a separate render of the fragment. ## Choosing between include and extends - Use **`extends`** when a page *is a kind of* layout: it fills named holes in a skeleton. - Use **`include`** when a page *contains* a reusable fragment: a card, a fare summary, a pagination bar. - When the fragment needs Python logic to compute its own data, a custom template tag is the tool; that is a separate topic. Keep fragment files small and name their inputs; `with ... only` is the discipline that makes a fragment safe to drop anywhere.