chameleon-rs

Chameleon templates, modernized. Several times faster.

chameleon-rs is Chameleon's template language on a new engine written in Rust. Your existing templates and code run unchanged, with byte-identical output, several times faster. It also adds what a modern Python web app expects: async rendering that never blocks the event loop, built-in integrations for Flask/Quart, FastAPI, Starlette, Robyn and Litestar, partials, Markdown, and support for free-threaded Python. No runtime dependencies.

Documentation: https://mkennedy.codes/docs/chameleon-rs/ · Changelog · Compatibility · Performance

Install

pip install chameleon-rs        # or: uv pip install chameleon-rs

CPython 3.12 to 3.15, including the free-threaded builds (3.14t, 3.15t). Wheels for Linux (glibc and musl), macOS and Windows contain the compiled engine, so no Rust toolchain is needed. Stock Chameleon need not be installed.

Already on Chameleon?

Switching an application is one line at startup, before anything imports Chameleon:

import chameleon_rs.compat

chameleon_rs.compat.install()

From then on import chameleon gives chameleon-rs, and so do chameleon_partials, chameleon_flask, fastapi_chameleon and chameleon_robyn. Your templates and the code around them stay as they are.

• Same output. Chameleon's own test suite, vendored unmodified, passes: 227 of the 227 tests that pass on Chameleon. All 122 of its fixture renders are byte-identical, and every page of two production Flask/Quart sites renders byte-identical HTML. Known differences.
• Check your own app first. Shadow mode (chameleon_rs.shadow.install()) renders a sample of real traffic with both engines and reports any difference, while Chameleon keeps serving. Switching from Chameleon.

Starting fresh?

Templates are Chameleon's: HTML with tal: attributes and ${...} expressions, so a template is still valid HTML that an editor or browser can open.

from chameleon_rs import PageTemplate

page = PageTemplate('<p tal:repeat="name names">Hello, ${name}!</p>')
print(page(names=['World', 'Rust']))

In a web app, point chameleon-rs at a template folder and decorate your views. With FastAPI:

import fastapi
import chameleon_rs.fastapi as fastapi_chameleon

app = fastapi.FastAPI()
fastapi_chameleon.configure(template_folder='templates', app=app)

@app.get('/episodes/{number}')                      # the route decorator first...
@fastapi_chameleon.template('episodes/detail.pt')   # ...then @template
async def detail(number: int):
    episode = await db.episode(number)
    if episode is None:
        fastapi_chameleon.not_found()
    return {'episode': episode}

The view keeps its signature, so path and query parameters, Depends, validation and the OpenAPI docs work as without @template. Getting started.

What's new compared with Chameleon

• Async rendering. await template.render_async(**model) awaits awaitable model values where the template uses them, without blocking the event loop. Macros, slots, partials and tal:on-error work across the wait, and with no awaitables the output is exactly render()'s. Opt-in concurrency: @chameleon_rs.concurrent helpers and concurrent=True partials run at the same time as the rest of the page. Async rendering.
• Framework integrations. Built in, with nothing extra to install (table below), and Pyramid's pyramid_chameleon runs unchanged. Async views render with render_async, and a @template written above its route decorator raises an error naming the fix instead of quietly returning JSON.
• Partials. Any template can call ${render_partial('shared/card.pt', item=item)}; the partial renders natively inside the page, 10.9x faster than chameleon_partials. Partials.
• Markdown. ${markdown: episode.notes} converts Markdown to HTML while the page renders: CommonMark plus the GitHub extensions (tables, task lists, footnotes, ...), converted in Rust, with raw HTML escaped by default. It's about 26x faster than mistune, a pure-Python converter, on a 5 KB document, and repeat conversions come from a cache in well under a microsecond. Opt-in with chameleon_rs.configure(markdown=True); named profiles (md-comment:) give different settings to different content. Markdown.
• One place for settings. chameleon_rs.configure(...) sets the template folder, auto_reload, partial lookup and Markdown for the whole process, thread-safely. Configuration.
• Free-threaded Python. Wheels for 3.14t and 3.15t that keep the GIL off. render_async(..., offload=True) (experimental) renders in a worker thread, in parallel with the event loop on a free-threaded build.
• Typed. PEP 561 type information for the whole API, including the native module.
• No runtime dependencies. The engine, the Markdown converter and the integrations are in the wheel; each integration imports its framework only when you import it.

Frameworks

Web frameworks shows the same page in each one. Each module keeps the API of the library it replaces and adds the same decorator API (configure, @template, render, response, not_found, error, render_async, response_async, check_views).

Template names come from your code. The decorator modules and render_partial() look names up as the original libraries do (.. and absolute paths work), so never build one from request data. Starlette's Templates and Litestar's ChameleonEngine refuse names that reach outside their folder, as Jinja does.

Performance

In synthetic benchmarks (release build, same process, interleaved with Chameleon): listings 6.6x faster per item, macro calls 6.9x, an app-shaped page 4.3x, native partials 10.9x, and templates compile about 70x faster. On a production Quart site, template rendering was 2.2x faster in total and whole requests 1.3x faster; under load, throughput rose 34%. The released wheels are profile-guided, about 10% faster again. How it's measured.

Development

make dev     # set up venv with the reference Chameleon and build the extension
make test    # Rust tests, Python tests, Chameleon's own suite on both engines

Licensed under Chameleon's license (see LICENSE.txt and COPYRIGHT.txt); this project ports Chameleon's behavior and reuses its test suite.