Skip to main content

blitz-py

CI PyPI

Render HTML/CSS to images from Python — no browser, no GPU, no JavaScript, no network.

Powered by Blitz, DioxusLabs' modular web engine: real CSS via Stylo (Servo/Firefox's style engine), flexbox/grid layout via Taffy, text shaping via Parley, and CPU rasterization via vello_cpu.

A 240×240 widget renders in ~1.5ms warm on an M-series Mac (~40ms for the first render). Output is deterministic and identical across platforms: the Inter font (SIL OFL 1.1) is bundled as the default face, so text renders the same on your laptop and in a fontless Alpine container.

What it looks like

Dashboard rendered from Tailwind v4 CSS: bento grid, SVG donut and sparkline, avatar stack, gradients

240x240 smart-display widget, hand-written CSS Bootstrap 5.3 card with buttons, badge, alert and progress bar

Unedited render_png output: a Tailwind v4 dashboard (grid, SVG donut + sparkline, gradients, avatar stack), a 240×240 widget, and Bootstrap 5.3 components.

Install

pip install blitz-py

Prebuilt wheels (abi3, Python ≥ 3.10): Linux glibc + musl (x86_64, aarch64), macOS (arm64, x86_64), Windows (x64, arm64).

No 32-bit (armv7l) wheels — this is an explicit drop, not an oversight: the rendering stack (anyrender 0.11) does not compile on 32-bit targets, and Home Assistant itself removed 32-bit support as of 2025.12. Frozen 32-bit installs on Pi 2/3 cannot use this package; we'll revisit if the engine gains 32-bit support.

Usage

import blitz_py

png = blitz_py.render_png(
    """
    <style>
      body { margin: 0; background: #000; color: #fff; font-family: sans-serif; }
      .screen { display: flex; flex-direction: column; align-items: center;
                justify-content: center; height: 240px; }
      .temp { font-size: 64px; font-weight: 600; }
      .label { color: #8e8e93; }
    </style>
    <body><div class="screen">
      <div class="temp">21.5&deg;</div>
      <div class="label">Living room</div>
    </div></body>
    """,
    width=240,
    height=240,
)
with open("out.png", "wb") as f:
    f.write(png)

Or get raw pixels for Pillow:

from PIL import Image

w, h, rgba = blitz_py.render_rgba(html, width=240, height=240)
Image.frombytes("RGBA", (w, h), rgba).convert("RGB").save("out.jpg", quality=90)

Animated GIFs

Animated dashboard: radar sweep, equalizer bars, deploy progress, typewriter terminal — pure CSS keyframes

Everything above is Tailwind classes + CSS @keyframes (source): satellites on different orbital periods, a live-scrolling traffic chart (a periodic series drawn two cycles wide, translated one cycle per loop — new data appears to stream in), an indeterminate progress sweep, and a steps()-driven typewriter — 48 frames rendered in ~220ms, seamless 4s loop.

CSS animations are evaluated on a deterministic clock: render_frames renders the document at any list of timestamps (seconds), and Pillow assembles the GIF. Frames after the first reuse the parsed document, so they're fast — ~1ms per 240×240 frame:

fps, seconds = 12, 3.2
gif = blitz_py.render_gif(
    html, width=240, height=240,
    times=[i / fps for i in range(int(fps * seconds))],
)
open("widget.gif", "wb").write(gif)   # ~16KB, encoded natively in ~20ms

Anything @keyframes can express — transforms, opacity, colors — loops perfectly because you control the clock. The encoder uses one shared palette (colors=64 by default), no dithering, and transparency-based inter-frame deltas — the combination that keeps UI-animation GIFs small. Frame delays follow the spacing of times. See examples/animated_widget.py.

Need custom encoding (dithering, APNG/WebP, per-frame palettes)? render_frames returns raw RGBA frames for Pillow/ffmpeg.

Fast repeated renders: Template

For dashboards and device widgets that re-render the same document with fresh data, parse once and mutate by element id:

tpl = blitz_py.Template(html, width=240, height=240)
tpl.update(temp="21.5°", hum="48%")       # batch text update, one round-trip, atomic
tpl.set_html("alerts", "".join(f"<li>{a}</li>" for a in alerts))  # re-render a region
tpl.set_style("bar", "width", "62%")
tpl.set_attribute("icon", "src", data_uri)
jpeg = tpl.render_jpeg(quality=90)        # ~0.5ms — straight to the device
gif = tpl.render_gif(times=[i/12 for i in range(38)])  # animated, current data

Templates are safe to share across threads (the document lives on its own worker thread), and renders release the GIL — 4 rendering threads get ~3.5× throughput.

Recipes

OG / social cards — deterministic, ~6ms per 1200×630 card, no Chromium to babysit:

OG card sample

card = blitz_py.render_png(OG_TEMPLATE, width=1200, height=630,
                           css_vars={"title": post.title, "kicker": post.tag})

Email-HTML previews — auto-height gives you the full message at client width:

png = blitz_py.render_png(email_html, width=600)   # height=None → sized to content

Visual snapshot tests — renders are byte-identical across platforms (CI-verified), so hashes are stable:

def test_widget_looks_right():
    png = blitz_py.render_png(widget_html, width=240, height=240)
    assert hashlib.sha256(png).hexdigest() == "9d62e494..."  # exact, on every OS

Device dashboards (the original use case) — Template + render_jpeg/render_gif for sub-millisecond updates pushed to small displays.

API

Six functions and a class, same keyword arguments:

render_png(html, *, width, height=None, ...) -> bytes       # PNG; height=None → content height
render_jpeg(html, *, width, height=None, quality=90, ...) -> bytes  # JPEG (opaque background)
render_rgba(html, *, width, height=None, ...) -> (w, h, bytes)   # raw RGBA pixels
render_frames(html, *, width, height, times, ...) -> (w, h, [bytes, ...])  # animation frames
render_gif(html, *, width, height, times, colors=64, ...) -> bytes  # looping GIF, native encoder
Template(html, *, width, height, ...)                       # parse once, re-render fast

Template methods: set_text(id, text) · update(**id_to_text) (batch, atomic) · set_html(id, fragment) (replace a region, new ids indexed) · set_style(id, prop, value) · set_attribute(id, name, value) · render_png/jpeg/rgba(time=...) · render_frames(times=...) · render_gif(times=..., colors=...)

Text measurement

measure_text exposes the engine's own shaper (Parley + the same font collection used for rendering), so Python-side fitting logic — ellipsis, autoscaling, wrapping estimates — uses the same metrics the renderer will use, instead of a second font system that drifts:

w, h = blitz_py.measure_text("Living room temperature", font_size=16, font_weight=600)
_, wrapped_h = blitz_py.measure_text(long_text, font_size=14, max_width=208.0)

def ellipsize(text, max_w, **kw):
    while text and blitz_py.measure_text(text + "…", **kw)[0] > max_w:
        text = text[:-1]
    return text + "…"
Argument Default Meaning
width, height required CSS-pixel viewport size
scale 1.0 Device-pixel ratio; output is width*scale × height*scale physical pixels. Use 2.0 for supersampled/hi-dpi output.
color_scheme "light" "light" or "dark" — drives @media (prefers-color-scheme: ...)
background "#ffffff" Base canvas color (#rgb, #rrggbb, #rrggbbaa), or None for transparent
base_url None Base for resolving relative URLs
css None Extra CSS appended after the document's styles (wins the cascade)
css_vars None Dict of CSS custom properties set on :root, e.g. {"accent": "#f00"}var(--accent)
fonts None List of font file bytes (TTF/OTF, variable fonts OK) to register
default_font_family None Family name to use for all CSS generic families (sans-serif, serif, ...) and as text fallback
allow_file_urls False Permit file:// URLs for images/resources

Images and resources

Rendering is fully offline. Embed images as data: URIs, or enable allow_file_urls=True and use file:// paths. http(s) URLs are intentionally ignored.

import base64
b64 = base64.b64encode(open("icon.png", "rb").read()).decode()
html = f'<img src="data:image/png;base64,{b64}" style="width:32px">'

CSS frameworks (Bootstrap, Tailwind, ...)

Any framework that ships as plain CSS works — inline it in a <style> tag:

css = open("bootstrap.min.css").read()  # fetch/cache it however you like
html = f"<style>{css}</style><body class='p-4'><div class='card'>...</div></body>"

Bootstrap 5 components (cards, buttons, badges, alerts, progress bars) render correctly. For Tailwind, run its build step and inline the generated CSS — the JS "Play CDN" won't work because there is no JavaScript engine. JS-driven behavior (modals opening, dropdowns) doesn't apply to static rendering anyway.

Fonts

Bundled Inter is the default for every CSS generic family and the Latin-script fallback, everywhere. Explicit family names (font-family: "Comic Sans MS") resolve against system fonts where available (macOS/Windows natively; Linux via fontconfig loaded at runtime if present — never a link dependency). To use your own font:

font = open("MyFont.ttf", "rb").read()
blitz_py.render_png(html, width=240, height=240,
                    fonts=[font], default_font_family="My Font")

@font-face also works with data: (or file://) sources — state the format explicitly, either as the unquoted CSS keyword or a bare extension string:

@font-face {
  font-family: MyWebFont;
  src: url(data:font/ttf;base64,...) format(truetype);  /* or format("ttf") */
}

WOFF/WOFF2 sources are supported too. local(...) sources and format-less data URIs are currently skipped by the engine.

Note on coverage: bundled Inter covers Latin scripts (plus Greek/Cyrillic). For CJK, Arabic, and other scripts on systems without suitable fonts, pass an appropriate font (e.g. a Noto variant) via fonts=.

What's supported

Modern CSS as implemented by Stylo/Taffy: flexbox, grid, gradients, border-radius, shadows, transforms, calc(), custom properties, media queries, SVG images, WOFF... No JavaScript, no @font-face fetching, no external resources. Blitz itself is pre-1.0: capable but not pixel-perfect against browsers.

Performance

Measured on an M-series Mac (arm64), each scenario in a fresh process, release build — reproduce with examples/bench.py:

Scenario Output px First render Warm render Peak RSS after 200 renders
<h1>Hello</h1> 200×100 35ms 0.5ms 42MB
240×240 widget @2× (flex + gradients) 480×480 32ms 1.8ms 45MB
Bootstrap 5.3 card (233KB CSS) 880×720 39ms 8.2ms 51MB
Tailwind v4 dashboard (the gallery image) 1520×1328 60ms 22ms 62MB
Long article 800×4000 56ms 21ms 73MB
Animated GIF: widget, 38 frames 240×240×38 56ms total 1.5ms/frame 76MB

GIF encoding on top of rendering (Pillow quantize + LZW, 38 frames): ~60ms, 18KB output.

More performance properties, all verified in CI or by examples/bench.py:

  • Template re-renders in ~0.4ms (parse and first style pass amortized away).
  • Thread scaling: the GIL is released during rendering; 4 threads → ~3.5× throughput.
  • Deterministic across platforms: CI renders a golden set on Linux, macOS, and Windows and asserts the outputs are byte-identical. Snapshot tests in your project can compare exact hashes.
  • Package ships type stubs (py.typed), so the API autocompletes and type-checks.

The first render pays a one-time system-font scan; after that the font collection is cached and cloned per render. Importing the module adds ~1MB RSS; memory stays flat under sustained rendering (no per-render growth — verified over 1000+ renders). On an Alpine/arm64 container the warm widget render measures ~0.8ms.

The GIL is released during rendering, so concurrent renders from Python threads scale and async event loops aren't blocked.

Why not a headless browser?

Playwright/Chromium render HTML too — at ~150MB+ of install, a browser process to babysit, and cold starts in the hundreds of milliseconds. blitz-py is a ~7MB self-contained wheel with millisecond renders, suitable for embedded targets like Home Assistant integrations generating widget images for small displays (its original use case).

License

MIT OR Apache-2.0. Bundled Inter font: SIL OFL 1.1 (assets/LICENSE-Inter.txt).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blitz_py-0.3.0.tar.gz (1.2 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

blitz_py-0.3.0-cp310-abi3-win_arm64.whl (4.7 MB view details)

Uploaded CPython 3.10+Windows ARM64

blitz_py-0.3.0-cp310-abi3-win_amd64.whl (5.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

blitz_py-0.3.0-cp310-abi3-musllinux_1_2_x86_64.whl (5.9 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

blitz_py-0.3.0-cp310-abi3-musllinux_1_2_aarch64.whl (5.5 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

blitz_py-0.3.0-cp310-abi3-manylinux_2_28_x86_64.whl (5.6 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

blitz_py-0.3.0-cp310-abi3-manylinux_2_28_aarch64.whl (5.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

blitz_py-0.3.0-cp310-abi3-macosx_11_0_arm64.whl (5.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

blitz_py-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file blitz_py-0.3.0.tar.gz.

File metadata

  • Download URL: blitz_py-0.3.0.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blitz_py-0.3.0.tar.gz
Algorithm Hash digest
SHA256 2a7fceee807dad6241ad936d3e81cd49cd1b0885cdd4c349e8b240b31055d786
MD5 e2c51ec6cca3f5f662ff6738a3d7ca97
BLAKE2b-256 d6eabf3805df5ec31dc30aaaea42523482bf188c9a006b1328f01bbd5f153e39

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0.tar.gz:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-win_arm64.whl.

File metadata

  • Download URL: blitz_py-0.3.0-cp310-abi3-win_arm64.whl
  • Upload date:
  • Size: 4.7 MB
  • Tags: CPython 3.10+, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 be30522616cfd2a44d74278ae9758734aa0e48c3ea13bcf21ce40aa492472d40
MD5 7cc3d95371376eef276b9c2870a31070
BLAKE2b-256 96703db216c524156587f5691c49c2654bf5e9adaf70ac1bef1830325aff91ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-win_arm64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: blitz_py-0.3.0-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 5.1 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 096f0d02275283dc0cd3cf7c191d1c5c07353ed14064f475328da5064f44a974
MD5 c4472572e614750b28eb61dc23a9cc11
BLAKE2b-256 94340c202feb29cda95acab80d4b628f995fd1d8da76b12afc6e0e11bf1581af

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-win_amd64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 6555c09e5fcf3b15551acb931c007ad2d2bdb4fbee1272ccbbe0ae9f0253d6e7
MD5 9fec13ca3435ec3e1cb5c49c945e388c
BLAKE2b-256 51dac1046c91a1fa2f8894f69f9a5cc2f677ba39216681dd121cf18436bf5c9d

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 4f14fdfaa55cb9e17f35981b268dbe878589506672e956cd7cdbbfcf53ec8700
MD5 172d01a51d5a6f4da9f10fe966fbb199
BLAKE2b-256 45cb06a49f3cded6335d261463b4b6497355363f48078fbcc50b06ee4963b048

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a836f3603408f28fd3ee13484809727b13bc747ed44732f2bbfc9781e91723dc
MD5 605cd02153475e3a395da477b8809ebf
BLAKE2b-256 9321202244338645d57a7eacebba37691517bf5efaf6490418552e921beb8854

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 92d075f08fc31612f26b7dd11f606ea46eef4b58e97b8f7746ff54d3ab33c495
MD5 335df53ef346340e0159182e5ef58abe
BLAKE2b-256 b25afa333eb2364465f07bf9fdae89234f73a5d7258a5a17e30053971431b581

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f338de684b6896c8efae86b551bc28844f2655f1b6974d2e9a0601c0046b491d
MD5 41e2ade87f93ac803a069e0574701a74
BLAKE2b-256 af22d8f65cd271996bebe926783ea5ea4e096193c263fa945f48e9282bc0a2ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file blitz_py-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for blitz_py-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c1935dbb89a43b5508e73c80d766cc74fc38d260ef272f00daef4e7c6892e24b
MD5 860cdf414fc8e274dd4d97b1e0cf7ebc
BLAKE2b-256 e30225256f286966e1107344413c7f760cffd6fa89aeaa899bb89772e8f24b5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for blitz_py-0.3.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: ci.yml on adrienbrault/blitz-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page