mjml-python

library1.4.1pypypi✓ verified 22d ago

mjml-python is a Python wrapper for MRML, a high-performance Rust port of MJML. It enables rendering MJML templates into email-compatible HTML entirely within Python, eliminating the need for external Node.js services or subprocesses. Currently at version 1.4.0, the library is actively maintained with regular updates, often coinciding with upstream MRML changes.

communication

pip install mjml-python

github ↗package ↗

INSTALL

IMPORT

SIG · MJML-PYTHON

mjml-python

communicationpythonv1.4.1

Install

1.6s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mjml2html

✓ from mjml import mjml2html

The primary function for converting MJML to HTML.

Render a basic MJML string to HTML. The `mjml2html` function takes the MJML string and optional keyword arguments for customization, such as disabling comments or specifying custom fonts. It returns a result object containing the rendered HTML and any errors encountered.

from mjml import mjml2html mjml_template = ''' <mjml> <mj-body> <mj-section> <mj-column> <mj-text font-size="20px" color="#F45E43">Hello World</mj-text> </mj-column> </mj-section> </mj-body> </mjml> ''' result = mjml2html(mjml_template, disable_comments=True, fonts={ "Open Sans": "https://fonts.googleapis.com/css?family=Open+Sans:300,400,500,700" } ) if result.errors: print("MJML rendering errors:", result.errors) else: print(result.html)

Debug

Known issues

gotchaThis `mjml-python` library is a wrapper for a Rust implementation (MRML) and is distinct from another `mjml` package on PyPI, which is a pure Python port. Ensure you install `mjml-python` for the Rust-backed performance benefits.

fix

Always use `pip install mjml-python` to ensure you get this specific wrapper.

affects: All versions

gotchaThe `mjml-python` library, while feature-rich, might not implement every single feature or component found in the official Node.js MJML implementation or other alternative Python ports. Always verify compatibility for advanced or less common MJML features.

fix

Consult the project's GitHub README for current limitations and supported features.

affects: All versions

gotchaWhen using `mjml-python` with user-supplied MJML templates, be aware of potential cross-site scripting (XSS) vulnerabilities if untrusted data is directly inserted into the templates. Like HTML, MJML itself does not inherently sanitize all inputs, and custom HTML in `mj-raw` tags or other components could render scripts.

fix

Strictly validate and sanitize any untrusted user input before incorporating it into MJML templates.

affects: All versions

breakingThe underlying MRML (Rust) library, which `mjml-python` wraps, undergoes major version bumps (e.g., v1.3.5 updated MRML to 5.0.0). While the `mjml-python` wrapper aims to maintain API stability, significant changes in MRML could potentially introduce subtle behavioral differences or require updates to MJML syntax expectations.

fix

Review `mjml-python` release notes and MRML changelogs when upgrading across `mjml-python` minor/major versions to identify any necessary adjustments to MJML templates or rendering options.

affects: Versions 1.3.5 and later (due to MRML 5.0.0 update), and future major MRML updates.

Errors

Common errors & fixes

ImportError: CSS inlining is an optional feature. Run `pip install -e ". [css_inlining]"` to install the required dependencies.

This error occurs when attempting to use CSS inlining functionality without having installed the necessary optional dependencies for it.

fix

Install the `css_inlining` extra by running `pip install "mjml-python[css_inlining]"`.

MjmlError: ParseError: Error while parsing the file / MjmlError: Invalid MJML / EmptyMJMLError: No root "<mjml>" or "<mj-body>" found in the file

These errors indicate that the provided MJML string is malformed, contains syntax errors, or is missing essential root tags like `<mjml>` or `<mj-body>`, preventing the MRML engine from parsing it correctly.

fix

Review the MJML input for syntax correctness, ensure it includes a root `<mjml>` tag and a `<mj-body>` tag, and validate it against the MJML specification. Example: `<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>`.

ImportError: cannot import name 'mjml_to_html' from 'mjml'

This error typically arises when the `mjml-python` library is either not installed, installed incorrectly, or the import statement used in the code is incorrect or refers to a non-existent object within the `mjml` package.

fix

Ensure `mjml-python` is correctly installed (`pip install mjml-python`) and use the correct import statement: `from mjml import mjml_to_html`.

Upgrade

Version history

1.4.1latest on PyPI · released Jun 30, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mgd020/mjml-python ↗

packagehttps://pypi.org/project/mjml-python/ ↗