Author: vkorobkov

• Dependency-free Mustache renderer for Python 3.12+.
• Supports upstream Mustache spec fixtures, including lambdas and dynamic partial names; inheritance is unsupported.
• Built for speed; with standard partial indentation respected, benchmarked at 3.3x Chevron, 3.1x mstache, and 3.5x Pystache.
• PEP 561 typed package.
• Supports Python mappings, objects, sequences, and callables as render data.
• Static partials are preloaded and inlined, eliminating render-time boundary overhead.

Fstache started from a Python web application built with server-side rendering, HTMX, Tailwind CSS, and Alpine.js.

That stack followed the HTML-over-the-wire style used by tools like HTMX and Hotwire/Turbo: keep rendering on the server, send HTML pages or fragments to the browser, and use JavaScript only for the interactions that genuinely need to happen on the client.

For many full-stack applications, this is a lower-cost and simpler default than building a separate client-side application. There is less state to duplicate between backend and frontend, fewer moving parts to operate, and less framework-specific code between the data and the HTML.

It is also friendly to backend-oriented developers. A small team can build useful, interactive web interfaces while staying close to the backend model, routing, validation, and deployment flow they already understand.

Mustache fit that approach because it is deliberately simple: templates render the data they receive. They do not become another layer for application logic, database access, or framework-specific behavior.

The problem showed up on a $4/month VPS. Rendering a full page with Chevron could take 5-10 ms. Smaller fragments were faster, but full-page rendering was still common enough to matter.

Looking for a faster drop-in renderer led to mstache, which was much faster than Chevron in that application. That raised the next question: how fast could a pure-Python Mustache renderer be while staying simple, dependency-free, and compatible with normal Mustache templates?

Fstache exists to answer that question for this style of Python web development: simple Mustache templates, no runtime dependencies, streaming-friendly output, and enough speed that rendering whole pages or fragments stays practical on modest servers.

Package page: fstache on PyPI

Create templates/hello.mustache:

Render it:

import fstache

render = fstache.create_renderer("./templates")
result = render("hello.mustache", {"name": "Ada"})
print(result.to_string())

Template names match file paths under the template root, including the file extension by default.

Output:

Use fstache render when you want a small shell-friendly render step:

fstache render --data data.json < page.mustache > page.html

The command reads the root template from stdin, reads JSON data from --data, writes rendered bytes to stdout, and writes diagnostics to stderr. For quick renders, pass the data inline with --json:

fstache render --json '{"name":"Ada"}' < page.mustache > page.html

--data and --json are mutually exclusive. Stdin always contains the root template, so --json - does not read data from stdin. If neither data option is provided, the command renders with {}.

Partials resolve from the current working directory:

{{> shared/header.mustache}}

Use --remove-extension when partial names omit the template extension:

fstache render --data data.json --remove-extension < page.mustache > page.html

Set --extension for another template file extension. The leading dot is optional:

fstache render --data data.json --extension .html --remove-extension < page.mustache > page.html

If an interpolation variable or partial template is missing, fstache render still writes the rendered result to stdout using an empty value for the missing tag. It also writes a clear diagnostic to stderr and exits with status 1.

Keep templates under one root:

templates/
├── pages/
│   └── home.mustache
└── partials/
    └── header.mustache

Create the renderer once at application startup, then reuse it:

import fstache

render = fstache.create_prod_renderer("./templates")

def render_home(data: object) -> bytes:
    return render("pages/home.mustache", data).to_bytes()

For streaming web responses, pass the rendered chunks to your framework:

from starlette.responses import StreamingResponse

async def homepage(request):
    result = render("pages/home.mustache", {"name": "Ada"})

    return StreamingResponse(
        result.iter_chunks(),
        media_type="text/html; charset=utf-8",
    )

For local development, use create_dev_renderer("./templates") so template edits are picked up without restarting and missing data fails fast. For tests, use create_test_renderer("./templates") to keep missing templates and variables strict while still preloading templates once.

• Django example shows Fstache with HttpResponse and StreamingHttpResponse in a standalone uv project.
• FastAPI example shows Fstache with HTMLResponse and StreamingResponse in a standalone uv project.
• Flask example shows Fstache with regular and streamed WSGI Response objects in a standalone uv project.
• Starlette example shows Fstache with HTMLResponse and StreamingResponse in a standalone uv project.

Choose one filesystem factory, keep the returned renderer around, and call it with a template name plus render data:

render = fstache.create_prod_renderer("./templates")
page = render("pages/home.mustache", data)

create_renderer is the full factory:

render = fstache.create_renderer(
    "./templates",
    extension=".mustache",
    remove_extension=False,
    delimiters=fstache.DEFAULT_DELIMITERS,
    ignore_indents=False,
    left_trim_source=False,
    preload_templates=True,
    resolve_missing_template=fstache.resolve_missing_template_as_error,
    resolve_missing_variable=fstache.resolve_missing_variable_as_none,
    escape=fstache.html_escape,
)

Renderer calls return a RenderedTemplate. Use .iter_chunks() for streaming bytes, .to_bytes() when you need one bytes value, and .to_string() for CLI output, tests, and debugging.

Supported Mustache tags include escaped and unescaped variables, dotted names, sections, inverted sections, variable and section lambdas, partials, dynamic partial names such as {{> * partial_name}}, comments, and delimiter changes. Inheritance is intentionally unsupported.

create_renderer preloads templates by default. It reads and compiles matching template files when the renderer is created, so later file edits are not visible until you create a new renderer:

render = fstache.create_renderer("./templates")

For local development, create_dev_renderer disables preloading by default so template edits, partial edits, and new template files are picked up without restarting the process. If you use create_renderer directly, set preload_templates=False:

render = fstache.create_renderer("./templates", preload_templates=False)

Avoid preload_templates=False in production. It reads and compiles templates during rendering, repeats filesystem work on each request, and delays syntax errors until the template is rendered.

Symlinked templates are allowed when their resolved target stays inside the template root. If a requested root template or partial resolves outside that root, it is treated as missing and uses resolve_missing_template.

The filesystem factories constrain stable paths to the template root, but they are not a filesystem sandbox. A concurrent writer can replace a validated directory with a symlink before it is read and redirect Fstache outside the root. See issue #6.

Live loading exposes this window on each template load; preloading limits it to renderer construction but does not eliminate it. Keep production templates and their parent directories immutable or writable only by trusted identities. If untrusted concurrent writes are unavoidable, isolate rendering with a container or an operating-system policy such as Landlock, SELinux, or AppArmor.

Partial tags load other templates from the same template root:

templates/
├── pages/
│   └── home.mustache
└── partials/
    ├── footer.mustache
    └── header.mustache

Below is the content of the templates/pages/home.mustache:

{{> partials/header.mustache}}
<main>
  <h1>{{title}}</h1>
</main>
{{> partials/footer.mustache}}

render("pages/home.mustache", {"title": "Dashboard"})

By default, standalone partials inherit the indentation before the partial tag. For example, this template:

Begin.
  {{> name.mustache}}
End.

with name.mustache:

renders as:

Set ignore_indents=True to skip that standalone partial indentation:

render = fstache.create_renderer("./templates", ignore_indents=True)

Set left_trim_source=True to remove leading spaces and tabs from every template source line before parsing. It applies to root templates, partials, and lambda templates:

render = fstache.create_renderer(
    "./templates",
    ignore_indents=True,
    left_trim_source=True,
)

So this source indentation:

  Begin.
    {{> name.mustache}}
  End.

renders to:

Inline whitespace is preserved. For example, {{first}} {{second}} still renders with the two spaces between values.

Use compact output for whitespace-insensitive output such as HTML where source indentation is mostly for template readability. In the workstation benchmark, ignore_indents=True rendered 4066.5 pages/sec versus 3102.2 pages/sec with standard standalone partial indentation.

create_renderer discovers .mustache files by default. Set extension when your templates use another file extension:

templates/
└── pages/
    └── home.html

render = fstache.create_renderer("./templates", extension=".html")
render("pages/home.html", data)

The leading dot is optional, so extension="html" behaves the same way.

With remove_extension=True, renderer calls and partial tags omit the file extension. For example, pages/home renders templates/pages/home.mustache:

render = fstache.create_renderer("./templates", remove_extension=True)
render("pages/home", data)

create_renderer renders missing variables as empty by default. To fail fast:

render = fstache.create_renderer(
    "./templates",
    resolve_missing_variable=fstache.resolve_missing_variable_as_error,
)

create_renderer raises MissingTemplateError when a root template or partial is missing. To render missing templates as empty:

render = fstache.create_renderer(
    "./templates",
    resolve_missing_template=fstache.resolve_missing_template_as_empty,
)

Pass a custom escape function when escaped variables need output-specific escaping. The function receives raw bytes and must return escaped bytes:

import fstache

def escape_brackets(value: bytes) -> bytes:
    return (
        fstache.html_escape(value)
        .replace(b"[", b"[")
        .replace(b"]", b"]")
    )

render = fstache.create_renderer("./templates", escape=escape_brackets)

The escape hook applies to escaped variable tags such as {{name}}. Unescaped tags such as {{{name}}} and {{& name}} bypass it.

Use Delimiters when templates start with a non-default tag pair:

render = fstache.create_renderer(
    "./templates",
    delimiters=fstache.Delimiters(start=b"[[", end=b"]]"),
)

Custom delimiters are the initial parser delimiters. Delimiter-change tags in template source can still update the active pair while parsing.

Use compile and render directly when your application owns template loading, caching, or precompiled templates:

import fstache

templates: dict[str, fstache.CompiledTemplate] = {
    "greeting": fstache.compile(b"Hello, {{name}}!\n", name="greeting"),
}

def load_template(name: str) -> fstache.CompiledTemplate:
    return templates[name]

result = fstache.render("greeting", {"name": "Ada"}, load_template)
print(result.to_string())

compile(...) accepts template bytes and returns an opaque CompiledTemplate. Treat it as a value passed to loaders, renderers, missing template resolvers, and inline_partials, not as a public node tree.

render(...) receives a root template name, render data, and a TemplateLoader callback. It returns RenderedTemplate, so consume the result with .iter_chunks(), .to_bytes(), or .to_string().

Pass any Python object as render data. The most common choices are dictionaries and application objects:

from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    name: str

data = {
    "site_name": "Docs",
    "user": User(name="Ada"),
}

render("profile.mustache", data)

Variable lookup starts in the current section scope and falls back to parent scopes. Mapping values use key lookup, while other objects use attributes and properties. Dotted names follow each part, so {{user.name}} works for both {"user": {"name": "Ada"}} and {"user": User(name="Ada")}.

Sections use normal Python truthiness. Missing and falsey values skip {{#section}} bodies and render {{^section}} bodies. Lists and tuples repeat the section once per item, using each item as the current scope. Truthy mappings and objects enter the section as a child scope; True renders the body without changing scope.

Variable values are rendered as bytes:

• str values are UTF-8 encoded.
• None and missing variables render as empty by default.
• Other scalar values render with str(value).
• bytes and memoryview values are rendered as byte chunks, avoiding string conversion and letting unescaped streaming output reuse the original bytes.
• A Fstache render result can be passed as a value to embed one rendered fragment in another without joining it first.

Escaped tags such as {{value}} apply the configured escape function, which may copy the bytes. Unescaped tags such as {{{value}}} and {{& value}} write bytes, memoryview, and embedded render-result chunks unchanged.

Renderer calls return a RenderedTemplate:

• .to_bytes() joins the rendered chunks into one bytes value.
• .iter_chunks() returns bytes | memoryview chunks for streaming. Use it when the consumer can accept chunks directly: it avoids joining the complete response into one bytes value, and static template fragments can be yielded without copying them into that joined value. See the render and compression experiment for measured time and Python heap trade-offs.
• .to_string(encoding="utf-8", errors="strict") joins and decodes the chunks as text. Use it for CLI output, tests, and debugging; web responses usually need bytes instead.

On the same workstation, Fstache 0.1.7 rendered a 91,094-byte HTML response with ignore_indents=True. Each timing includes both rendering and compression. The uncompressed render took 0.252 ms (3972.1 renders per second).

In this run, Zstandard was the fastest compressor and Brotli produced the smallest response. Passing RenderedTemplate.iter_chunks() through one continuous compressor used less traced Python heap, but was slower for every compressor. The heap figures come from tracemalloc and exclude allocations inside native compression libraries.

The chunk variants used one compressor context, finalized it once, and did not call to_bytes(), join the response, or flush between Fstache chunks. Across 905 input chunks, Brotli and Zstandard emitted no bytes before finalization; gzip emitted only its 10-byte header. Real HTTP latency therefore depends on an application's flush policy and any server or proxy buffering.

The run used Brotli 1.2.0, Zstandard 0.25.0, and zlib-ng 1.3.1 on CPython 3.14.6.

• The benchmark renders a realistic, heavy marketing/docs HTML page from the source Mustache templates, JSON data, and perf script:
  • About 100 KiB of rendered HTML (source) from 15 Mustache templates, including 14 partial files.
  • Tailwind CSS v4 utility-heavy markup with Alpine.js attributes, inline SVG icons, responsive navigation, cards, tables, accordions, and form controls.
  • About 15 KiB of JSON context data with nested arrays for navigation, feature cards, testimonials, a recursive docs tree, comparison rows, blog posts, changelog entries, FAQs, and pricing plans.
  • 42 section, inverted-section, and partial references, including 24 section tags for loops and conditionals plus recursive node partial rendering.
• The benchmark isolates render throughput from setup work:
  • Each engine preloads the template files and partials during setup.
  • Each engine uses the closest available precompiled, preparsed, or pretokenized representation for the layout and partials.
  • The timed render loop excludes disk I/O and one-time template preparation.