Mistune Markdown Parser

3.2.0 verified Tue May 12 auth: no python install: verified quickstart: verified

Mistune is a sane and fast Markdown parser for Python, offering various useful plugins and renderers. It is actively maintained, with the current version being 3.2.0, and receives regular updates to support newer Python versions and fix bugs.

pip install mistune

Common errors

error AttributeError: module 'mistune' has no attribute 'BlockGrammar' ↓

cause This error frequently occurs when a project or a dependency (like `nbconvert` or `m2r`) is written for `mistune` v0.x or v1.x, but `mistune` v2.x or v3.x (like 3.2.0) is installed, as the internal API, including `BlockGrammar`, was completely redesigned in `mistune` v2 and is no longer directly exposed.

fix

If this error originates from a dependent package, try updating that package to a version compatible with mistune v3.2.0. If no compatible version exists, you might need to downgrade mistune to mistune<2 (e.g., pip install "mistune<2") to match the dependent package's requirements. If you are directly using mistune, refactor your code to use the modern mistune v3.x API for custom parsers and renderers, which involves mistune.create_markdown and custom renderer classes or plugins.

error ImportError: cannot import name 'AstRenderer' from 'mistune.renderers' ↓

cause In `mistune` v3.x (including 3.2.0), `AstRenderer` (and `HTMLRenderer`) are no longer imported from `mistune.renderers`. Instead, they are directly available under the `mistune` namespace or by using the `renderer` argument in `mistune.create_markdown`.

fix

Change the import statement from from mistune.renderers import AstRenderer to from mistune import AstRenderer (or HTMLRenderer). Alternatively, use markdown = mistune.create_markdown(renderer="ast") for AST output.

error ModuleNotFoundError: No module named 'mistune' ↓

cause The `mistune` library is not installed in the current Python environment or is not accessible on the `sys.path`.

fix

Install the library using pip: pip install mistune.

error ModuleNotFoundError: No module named 'mistune.plugins' ↓

cause This error can occur if you are trying to import plugins directly from `mistune.plugins` in an older `mistune` version (pre-v2) where they might not have existed, or if there's a problem with how plugins are accessed in a v3 installation. In `mistune` v3.2.0, standard plugins are typically used by passing their names as strings to `mistune.create_markdown(plugins=[...])` or by importing specific plugin functions from `mistune.plugins` for custom configurations.

fix

Ensure you are using mistune v3.x. For built-in plugins, pass their names as strings to mistune.create_markdown: markdown = mistune.create_markdown(plugins=['strikethrough', 'table']). If you need to customize or create a plugin, you would import its base components, e.g., from mistune.plugins import strikethrough.

Warnings

breaking Mistune v3 introduced significant breaking changes compared to v2, particularly in custom renderer methods' parameters and the redesign of directives. Migrating existing code, especially custom plugins or renderers, will require updates. ↓

fix Refer to the official 'Upgrade Guide' for detailed changes. Parameter signatures for custom renderer methods and directive handling have been altered. For instance, `RstDirective` was renamed to `RSTDirective`.

gotcha The default behavior for HTML escaping differs between `mistune.html()` and `mistune.create_markdown()`. `mistune.html()` does not escape raw HTML tags by default, while `mistune.create_markdown()` (without `escape=False`) *does* escape HTML. ↓

fix If using `create_markdown()`, explicitly set `escape=False` in its parameters if you want raw HTML to be rendered directly: `mistune.create_markdown(escape=False)`. Always be mindful of potential XSS vulnerabilities when disabling HTML escaping for untrusted input.

gotcha While a global `mistune.markdown()` function exists, for performance-critical applications or when using custom configurations and plugins, it is recommended to create and reuse a `Markdown` instance (e.g., via `mistune.create_markdown()`) rather than calling the global function repeatedly. ↓

fix Initialize a Markdown instance once using `markdown = mistune.create_markdown(...)` and then call `markdown(text)` for subsequent conversions.

gotcha Versions of Mistune v3 prior to 3.0.2 experienced a `RecursionError` when parsing complex lists. ↓

fix Upgrade to `mistune>=3.0.2` to resolve potential `RecursionError` issues with list parsing.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.11s 18.5M

3.10 slim (glibc) - - 0.10s 19M

3.11 alpine (musl) - - 0.10s 20.2M

3.11 slim (glibc) - - 0.14s 21M

3.12 alpine (musl) - - 0.12s 12.0M

3.12 slim (glibc) - - 0.07s 13M

3.13 alpine (musl) - - 0.09s 11.6M

3.13 slim (glibc) - - 0.07s 12M

3.9 alpine (musl) - - 0.06s 18.0M

3.9 slim (glibc) - - 0.07s 19M

Imports

html
```
import mistune
html_output = mistune.html(markdown_text)
```
The `mistune.html()` function is the recommended high-level entry point for converting Markdown to HTML with common features enabled by default (e.g., no HTML escape, strikethrough, table, footnote plugins).

create_markdown

wrong

from mistune import Markdown
renderer = mistune.HTMLRenderer()
markdown = Markdown(renderer, plugins=['strikethrough'])

correct

from mistune import create_markdown
markdown = create_markdown(plugins=['strikethrough'])
html_output = markdown(markdown_text)

`create_markdown()` is the preferred factory function for creating customizable Markdown instances with specific renderers and plugins, simplifying setup compared to manually instantiating `Markdown` and `HTMLRenderer`.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates the simplest way to convert Markdown text to HTML using the `mistune.html()` function, which provides a default setup with many common features enabled.

import mistune

markdown_text = """
# Hello, Mistune!

This is **bold** text and `code`.

- Item 1
- Item 2
"""

html_output = mistune.html(markdown_text)
print(html_output)