A fast library for rendering HTML/CSS to images

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

These details have not been verified by PyPI

Project description

dynimg

A fast library and CLI for rendering HTML/CSS to images. Use from Python, Rust, or the command line. Built on Blitz, a modular Rust rendering engine.

Perfect for generating dynamic images like Open Graph (OG) images, social media cards, email headers, and more.

Features

Python + Rust + CLI: Use from Python, as a Rust library, or command-line tool
Multiple output formats: PNG, WebP (lossless), and JPEG
High-quality rendering: Configurable scale factor for retina displays
Fast: Native Rust performance with no browser overhead
Secure by default: Network and filesystem access disabled unless explicitly enabled

Installation

Python

pip install dynimg

Rust CLI

cargo install dynimg

Rust Library

[dependencies]
dynimg = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Library Usage

use dynimg::{render, RenderOptions};

#[tokio::main]
async fn main() -> Result<(), dynimg::Error> {
    let html = r#"
        <html>
        <body style="background: linear-gradient(135deg, #667eea, #764ba2);
                     display: flex; justify-content: center; align-items: center;
                     height: 630px; margin: 0;">
            <h1 style="color: white; font-family: system-ui; font-size: 64px;">
                Hello World
            </h1>
        </body>
        </html>
    "#;

    // Render with default options (1200×auto viewport, 2x scale)
    let image = render(html, RenderOptions::default()).await?;

    // Save as PNG
    image.save_png("output.png")?;

    // Or get raw bytes
    let png_bytes = image.to_png()?;
    let webp_bytes = image.to_webp();
    let jpeg_bytes = image.to_jpeg(90)?;

    Ok(())
}

Configuration

use dynimg::RenderOptions;

// Using builder pattern
let options = RenderOptions::default()
    .width(1200)
    .height(630)
    .scale(2.0)
    .allow_net()
    .assets_dir("./assets");

// Or struct initialization
let options = RenderOptions {
    width: 1200,
    height: Some(630),
    scale: 2.0,
    allow_net: true,
    assets_dir: Some("./assets".into()),
    base_url: None,
};

Convenience function

use dynimg::{render_to_file, RenderOptions};

// Render directly to a file (format detected from extension)
render_to_file(html, "output.png", RenderOptions::default(), 90).await?;

CLI Usage

Basic Usage

Render an HTML file to PNG:

dynimg input.html -o output.png

Output Formats

# PNG (lossless)
dynimg input.html -o image.png

# WebP (lossless)
dynimg input.html -o image.webp

# JPEG (lossy)
dynimg input.html -o image.jpg --quality 90

Image Dimensions

The --width and --height options set the viewport size (CSS layout dimensions). The actual output image is scaled by the --scale factor (default: 2x for high-DPI/retina displays).

Output image size = viewport × scale

# Default: 1200px viewport → 2400px output (at 2x scale)
dynimg input.html -o output.png

# OG image: 1200×630 viewport → 2400×1260 output
dynimg input.html -o output.png --width 1200 --height 630

# 1x scale for exact pixel dimensions (1200×630 output)
dynimg input.html -o output.png --width 1200 --height 630 --scale 1

# 3x scale for extra-high-DPI (3600×1890 output)
dynimg input.html -o output.png --width 1200 --height 630 --scale 3

Your HTML/CSS should use the viewport dimensions (e.g., width: 1200px) - the scale factor handles the high-resolution rendering.

Reading from stdin

echo '<html><body><h1>Hello</h1></body></html>' | dynimg - -o output.png

Loading External Resources

By default, network and filesystem access are disabled for security. Enable them to load images, fonts, and other resources:

# Load images/fonts from URLs
dynimg input.html -o output.png --allow-net

# Load images/fonts from a local assets directory
dynimg input.html -o output.png --assets ./assets

# Allow both
dynimg input.html -o output.png --allow-net --assets ./assets

When using --assets, all local paths are resolved relative to the asset directory. Attempts to load files outside this directory will error:

<!-- With --assets ./assets -->
<img src="logo.png">         <!-- loads ./assets/logo.png -->
<img src="img/hero.png">     <!-- loads ./assets/img/hero.png -->
<img src="../secret.png">    <!-- ERROR: outside assets directory -->

For self-contained templates, consider using inline base64 data URIs instead:

<img src="data:image/png;base64,iVBORw0KGgo...">

CLI Reference

dynimg [OPTIONS] <INPUT> -o <OUTPUT>

Arguments:
  <INPUT>   HTML file path or '-' for stdin

Options:
  -o, --output <FILE>       Output image path (format detected from extension)
  -w, --width <PIXELS>      Viewport width in CSS pixels [default: 1200]
  -H, --height <PIXELS>     Viewport height in CSS pixels [default: document height]
  -s, --scale <FACTOR>      Scale multiplier for output (2 = 2x resolution) [default: 2]
  -q, --quality <1-100>     JPEG quality [default: 90]
      --allow-net           Allow network access for loading remote resources
      --assets <DIR>        Asset directory for local resources
  -v, --verbose             Enable verbose logging
      --help                Print help
      --version             Print version

Options can also be set via HTML meta tags (see below). CLI flags override meta tags.

Note: Output image dimensions = viewport × scale. A 1200×630 viewport at 2x scale produces a 2400×1260 image.

Python Usage

import dynimg

html = """
<html>
<body style="background: linear-gradient(135deg, #667eea, #764ba2);
             display: flex; justify-content: center; align-items: center;
             height: 630px; margin: 0;">
    <h1 style="color: white; font-family: system-ui; font-size: 64px;">
        Hello World
    </h1>
</body>
</html>
"""

# Render with default options
image = dynimg.render(html)

# Save to file
image.save("output.png")

# Or get bytes
png_bytes = image.to_png()
webp_bytes = image.to_webp()
jpeg_bytes = image.to_jpeg(quality=90)

Configuration

import dynimg

options = dynimg.RenderOptions(
    width=1200,          # Viewport width (default: 1200)
    height=630,          # Viewport height (default: auto)
    scale=2.0,           # Output scale factor (default: 2.0)
    allow_net=True,      # Allow network requests (default: False)
    assets_dir="./assets",  # Local assets directory (default: None)
    base_url="https://example.com",  # Base URL for relative URLs (default: None)
)

image = dynimg.render(html, options)

Direct File Output

# Render directly to a file (format detected from extension)
dynimg.render_to_file(html, "output.png")

# With options
dynimg.render_to_file(html, "output.png", options=options)

# JPEG with quality setting
dynimg.render_to_file(html, "output.jpg", quality=90)

Image Properties

image = dynimg.render(html)
print(f"Size: {image.width}x{image.height}")
print(f"Bytes: {len(image.data)}")

HTML Meta Tags

You can configure rendering options directly in your HTML using meta tags. CLI flags take precedence over meta tags.

<meta name="dynimg:width" content="1200">   <!-- viewport width -->
<meta name="dynimg:height" content="630">   <!-- viewport height -->
<meta name="dynimg:scale" content="2">      <!-- output multiplier -->
<meta name="dynimg:quality" content="90">   <!-- JPEG quality -->

This is useful for templates that should always render at specific dimensions. Remember: the output image size is viewport × scale.

Example HTML Template

<!DOCTYPE html>
<html>
<head>
  <meta name="dynimg:width" content="1200">
  <meta name="dynimg:height" content="630">
  <style>
    .container {
      width: 1200px;
      height: 630px;
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      font-family: system-ui, sans-serif;
    }
    h1 {
      color: white;
      font-size: 64px;
      margin: 0;
    }
    p {
      color: rgba(255,255,255,0.8);
      font-size: 32px;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Hello World</h1>
    <p>Welcome to my site</p>
  </div>
</body>
</html>

Supported CSS Features

dynimg uses Blitz for rendering, which supports:

Flexbox and Grid layouts
CSS variables
Media queries
Complex selectors
Gradients and shadows
Web fonts (via @font-face, requires --allow-net or --assets)
Images (requires --allow-net or --assets, or use data URIs)

Performance

dynimg is designed for speed:

No browser startup overhead
Native Rust rendering pipeline
Efficient image encoding

Typical rendering time: 50-200ms depending on complexity.

Development

Building

# Build CLI
cargo build --release

# Build Python wheel
pip install maturin
maturin build --release --features python

# Install locally for development
maturin develop --features python

Running Tests

cargo test
cargo clippy -- -D warnings
cargo fmt -- --check

Releasing

Releases are automated via GitHub Actions. To create a new release:

Update the version in Cargo.toml
Create and push a git tag:

git tag v0.1.0
git push origin v0.1.0

This triggers the release workflow which:

Builds wheels for Linux (x86_64, aarch64) and macOS (x86_64, aarch64)
Creates a GitHub Release with all artifacts
(Optional) Publishes to PyPI (when enabled)

License

MIT

AI Warning

This is AI slop, if you want to use it, fork and make it your own!

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

blopker

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.1.22

Mar 26, 2026

0.1.21

Feb 27, 2026

0.1.19

Feb 27, 2026

0.1.18

Feb 27, 2026

0.1.17

Feb 22, 2026

0.1.16

Feb 7, 2026

0.1.15

Feb 4, 2026

0.1.14

Feb 4, 2026

0.1.13

Jan 30, 2026

This version

0.1.11

Jan 29, 2026

0.1.10

Jan 29, 2026

0.1.9

Jan 29, 2026

Download files

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

Source Distribution

dynimg-0.1.11.tar.gz (226.0 kB view details)

Uploaded Jan 29, 2026 Source

Built Distributions

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

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.8 MB view details)

Uploaded Jan 29, 2026 CPython 3.11+manylinux: glibc 2.17+ x86-64

dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (8.4 MB view details)

Uploaded Jan 29, 2026 CPython 3.11+manylinux: glibc 2.17+ ARM64

dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl (7.3 MB view details)

Uploaded Jan 29, 2026 CPython 3.11+macOS 11.0+ ARM64

dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl (7.7 MB view details)

Uploaded Jan 29, 2026 CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file dynimg-0.1.11.tar.gz.

File metadata

Download URL: dynimg-0.1.11.tar.gz
Upload date: Jan 29, 2026
Size: 226.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dynimg-0.1.11.tar.gz
Algorithm	Hash digest
SHA256	`c11366070f94b3862b9468221844a333d17cf9f2a0be588b3e6700b84af5cf1d`
MD5	`073873f90108897e8bb808725f18bc58`
BLAKE2b-256	`f6740ee07264e2a6e6f9a76e581d7440c9ec7c94f0bf23feb3f31262725e3181`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dynimg-0.1.11.tar.gz:

Publisher: release.yml on blopker/dynimg

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dynimg-0.1.11.tar.gz
- Subject digest: c11366070f94b3862b9468221844a333d17cf9f2a0be588b3e6700b84af5cf1d
- Sigstore transparency entry: 869248592
- Sigstore integration time: Jan 29, 2026
Source repository:
- Permalink: blopker/dynimg@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Branch / Tag: refs/tags/v0.1.11
- Owner: https://github.com/blopker
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Trigger Event: push

File details

Details for the file dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jan 29, 2026
Size: 8.8 MB
Tags: CPython 3.11+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`3f3e7b30d0ff46dbeead9ab3535983fd30025fcdc5d2e84cac66a21f7b68bec1`
MD5	`73f33a3b22cbd74d90701f94c79a2b15`
BLAKE2b-256	`0ac5798c73fa995d9c224ea64990b782a904d77440e92c4dfc1d7f930d62b0cd`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on blopker/dynimg

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dynimg-0.1.11-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 3f3e7b30d0ff46dbeead9ab3535983fd30025fcdc5d2e84cac66a21f7b68bec1
- Sigstore transparency entry: 869248607
- Sigstore integration time: Jan 29, 2026
Source repository:
- Permalink: blopker/dynimg@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Branch / Tag: refs/tags/v0.1.11
- Owner: https://github.com/blopker
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Trigger Event: push

File details

Details for the file dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Jan 29, 2026
Size: 8.4 MB
Tags: CPython 3.11+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`2a58ee19ccf10eaadd663d1d105498b749710738845529ffa333261616cda51a`
MD5	`32e8aa5fb11676511e378377fa5492e2`
BLAKE2b-256	`bca7a00b0b936746ed0a4f5d085f9eecfa2e49aa51661a27df6ca8dc57222894`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on blopker/dynimg

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dynimg-0.1.11-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 2a58ee19ccf10eaadd663d1d105498b749710738845529ffa333261616cda51a
- Sigstore transparency entry: 869248612
- Sigstore integration time: Jan 29, 2026
Source repository:
- Permalink: blopker/dynimg@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Branch / Tag: refs/tags/v0.1.11
- Owner: https://github.com/blopker
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Trigger Event: push

File details

Details for the file dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl
Upload date: Jan 29, 2026
Size: 7.3 MB
Tags: CPython 3.11+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`18b9a1be7884987aeb6887ac324eb1b48576cc7e097dffbb9732911251a31003`
MD5	`02b5640687f04871c7f7e04f4a3a27f9`
BLAKE2b-256	`012d6af2fdcf199432496fc652ef27bfa87a960aca57e8f533c6016682c17126`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on blopker/dynimg

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dynimg-0.1.11-cp311-abi3-macosx_11_0_arm64.whl
- Subject digest: 18b9a1be7884987aeb6887ac324eb1b48576cc7e097dffbb9732911251a31003
- Sigstore transparency entry: 869248624
- Sigstore integration time: Jan 29, 2026
Source repository:
- Permalink: blopker/dynimg@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Branch / Tag: refs/tags/v0.1.11
- Owner: https://github.com/blopker
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Trigger Event: push

File details

Details for the file dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl
Upload date: Jan 29, 2026
Size: 7.7 MB
Tags: CPython 3.11+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`de85843e7e4beb756921055d10e971fe1166d067b881f548646af7311c5349ff`
MD5	`9677cf46905024433cf9cf435ceac54e`
BLAKE2b-256	`1057046e619c94e2cd4d42b49668e795a343531cb5e80d26aabcf13f73f884ea`

See more details on using hashes here.

Provenance

The following attestation bundles were made for dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on blopker/dynimg

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

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: dynimg-0.1.11-cp311-abi3-macosx_10_12_x86_64.whl
- Subject digest: de85843e7e4beb756921055d10e971fe1166d067b881f548646af7311c5349ff
- Sigstore transparency entry: 869248601
- Sigstore integration time: Jan 29, 2026
Source repository:
- Permalink: blopker/dynimg@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Branch / Tag: refs/tags/v0.1.11
- Owner: https://github.com/blopker
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@e4c868702ba054d6a51bb0bfbdefeddf8f5cff74
- Trigger Event: push

dynimg 0.1.11

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

dynimg

Features

Installation

Python

Rust CLI

Rust Library

Library Usage

Configuration

Convenience function

CLI Usage

Basic Usage

Output Formats

Image Dimensions

Reading from stdin

Loading External Resources

CLI Reference

Python Usage

Configuration

Direct File Output

Image Properties

HTML Meta Tags

Example HTML Template

Supported CSS Features

Performance

Development

Building

Running Tests

Releasing

License

AI Warning

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance