Install & Compatibility
Where this runs
tested against v1.6.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.644s · 18.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 1.652s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
markdown
✓ from mistletoe import markdown
HTMLRenderer
✓ from mistletoe import Document, HTMLRenderer
LaTeXRenderer
✓ from mistletoe import Document, LaTeXRenderer
PygmentsRenderer
✓ from mistletoe.contrib.pygments_renderer import PygmentsRenderer
✗ from mistletoe.pygments_renderer import PygmentsRenderer
Prior to v1.0.0, renderers in the 'contrib' module were directly under the `mistletoe` package. Since v1.0.0, they moved to `mistletoe.contrib`.
This quickstart demonstrates basic Markdown to HTML conversion using the `mistletoe.markdown` function and how to extend `HTMLRenderer` to customize the output, such as adding a CSS class to headings.
from mistletoe import markdown
# Basic Markdown to HTML conversion
markdown_text = "# Hello, Mistletoe!\n\nThis is **bold** text and `code`."
html_output = markdown(markdown_text)
print(f"Basic HTML output:\n{html_output}\n")
# Using a custom renderer to modify output
from mistletoe import Document, HTMLRenderer
class CustomHTMLRenderer(HTMLRenderer):
def render_heading(self, token):
# Add a custom class to all headings
return f'<h{token.level} class="custom-heading">{self.render_inner(token)}</h{token.level}>'
with CustomHTMLRenderer() as renderer:
document = Document(markdown_text)
custom_html = renderer.render(document)
print(f"Custom HTML output:\n{custom_html}")
Debug
Known issues
breakingThe `contrib` module (containing renderers like `PygmentsRenderer`) was moved from directly under the `mistletoe` package to `mistletoe.contrib`.fixUpdate import statements from `from mistletoe.<renderer> import ...` to `from mistletoe.contrib.<renderer> import ...`.
affects: v1.0.0 and newer
breakingThe `children` attribute of tokens changed to a property. Direct checks like `hasattr(token, 'children')` or `'children' in vars(token)` no longer work as expected.fixReplace checks with `token.children is not None` to determine if a token has children, or use `token.children or []` to safely access children, providing an empty list if none exist.
affects: v1.4.0 and newer
breakingPython 3.5 became the minimum required version. Older Python versions are no longer supported.fixEnsure your project is running on Python 3.5 or a newer compatible version.
affects: v0.9.0 and newer
gotchaBy default, tables are now allowed to interrupt paragraphs, aligning with GFM behavior. This might change parsing results for certain Markdown inputs.fixIf you require the old behavior where tables do not interrupt paragraphs, set `mistletoe.block_token.Table.interrupt_paragraph = False` at the start of your application.
affects: v1.2.0 and newer
deprecatedThe `FileWrapper.anchor()` and `FileWrapper.reset()` methods are deprecated.fixUse the more versatile `FileWrapper.get_pos()` and `FileWrapper.set_pos()` methods instead.
affects: v1.2.0 and newer
breakingHTML character references (entities) are now correctly unescaped during the parsing phase. Custom renderers that previously performed their own unescaping might double-unescape or behave unexpectedly.fixRemove any custom HTML unescaping logic from your renderers, as this is now handled upstream by the parser.
affects: v0.9.0 and newer
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mistletoe'
The 'mistletoe' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install mistletoe'.
ImportError: cannot import name 'Document' from 'mistletoe'
The 'Document' class is not directly accessible from the 'mistletoe' module.
fixImport 'Document' from 'mistletoe.block_token': 'from mistletoe.block_token import Document'.
TypeError: 'NoneType' object is not iterable
Attempting to iterate over a 'None' value, possibly due to a parsing error or empty input.
fixEnsure the input to the parser is valid and not empty before processing.
AttributeError: module 'mistletoe' has no attribute 'markdown'
The 'markdown' function is not a direct attribute of the 'mistletoe' module.
fixUse the 'markdown' function from 'mistletoe': 'from mistletoe import markdown'.
ImportError: cannot import name 'HTMLRenderer' from 'mistletoe'
The 'HTMLRenderer' class is located in the 'mistletoe.html_renderer' module.
fixImport 'HTMLRenderer' from 'mistletoe.html_renderer': 'from mistletoe.html_renderer import HTMLRenderer'.
Upgrade
Version history
1.6.0latest on PyPI · released Jul 11, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.5 or newer.