Install & Compatibility
Where this runs
tested against v0.6.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.044s · 18.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.040s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Renderer
✓ from pystache import Renderer
✗ import pystache
render
✓ from pystache import render
✗ import pystache
TemplateSpec
✓ from pystache import TemplateSpec
✗ import pystache
This quickstart demonstrates the basic usage of Pystache with direct rendering, using the Renderer class for more control, and integrating with a simple Python object as a 'view' for data.
import pystache
# Simplest rendering
template = "Hello, {{person}}!"
context = {"person": "World"}
print(pystache.render(template, context))
# Using Renderer for more control (e.g., custom template directories)
renderer = pystache.Renderer()
print(renderer.render(template, context))
# Using a dedicated view class (no inheritance needed since 0.5.0)
class SayHello:
def to(self):
return "Pizza"
hello_view = SayHello()
template_view = "Hello, {{to}}!"
print(renderer.render(template_view, hello_view))
pystache --version
Debug
Known issues
breakingPystache 0.5.0 introduced significant API changes, including the removal of the `View` class and replacement of the `Template` class with `Renderer`. Code written for pre-0.5.0 versions will require updates.fixMigrate from `View` to plain Python objects or `TemplateSpec` with `Renderer`. Adjust template rendering calls to use `pystache.render()` or `Renderer` instances.
affects: <0.5.0
gotchaThe default HTML escape function behaves differently between Python 2 (not escaping single quotes with `cgi.escape()`) and Python 3 (escaping single quotes with `html.escape()`). This can lead to subtle rendering differences or unexpected security issues if not accounted for.fixExplicitly set a custom escape function via `Renderer(escape=my_escape_func)` if consistent escaping behavior, especially for single quotes, is critical across Python versions.
affects: All versions (behavior difference across Python major versions)
gotchaPystache internally uses unicode. When passing byte strings as input (e.g., from files or network), explicit encoding attributes (`file_encoding`, `string_encoding`, `decode_errors`) on the `Renderer` might be necessary to control conversion and prevent `UnicodeDecodeError` or incorrect rendering.fixConfigure `Renderer` with appropriate `file_encoding`, `string_encoding`, and `decode_errors` parameters, or ensure all template inputs are explicitly unicode strings (Python 3 `str`).
affects: All versions
gotchaIf installing from source, Pystache's original code was written for Python 2 and must be converted (e.g., by `2to3`) for Python 3 environments. Importing directly from an unconverted Python 2 source directory in a Python 3 environment will result in a `SyntaxError`.fixAlways install via `pip` which handles the conversion automatically, or ensure manual `2to3` conversion if importing from a source checkout.
affects: All versions when installing from source for Python 3
gotchaThe `{{.}}` tag (implicit iterator) is supported for accessing the current value within a section context (e.g., when iterating over a list of simple values). While useful, its behavior is not always intuitive and was a later addition to the Mustache spec.fixUnderstand the Mustache spec's definition of implicit iterators. Use `{{.}}` primarily within sections iterating over primitive values where you want to render the value itself. For objects, refer to specific properties (e.g., `{{name}}`). affects: All versions
Upgrade
Version history
0.6.8latest on PyPI · released Mar 18, 2025
Audit
Dependencies
PyYAMLoptionalOptional dependency for running spec tests and command-line interface, especially when parsing YAML versions of the Mustache spec.