markdown-it-py

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

markdown-it-py is a Python port of the popular markdown-it library, providing fast and extensible Markdown parsing with full CommonMark compliance. The current version is 4.0.0, released in August 2025, with a release cadence of approximately one major version per year.

pip install markdown-it-py

Common errors

error ModuleNotFoundError: No module named 'markdown_it' ↓

cause The markdown-it-py library is not installed in your Python environment, or you are attempting to import it with an incorrect module name (e.g., 'markdown-it' instead of 'markdown_it').

fix

Ensure the library is installed using pip: pip install markdown-it-py. Then, import it as from markdown_it import MarkdownIt.

error ImportError: cannot import name 'some_plugin' from 'mdit_py_plugins' ↓

cause You are trying to import a plugin (e.g., `front_matter_plugin`, `footnote_plugin`) that is part of the `mdit-py-plugins` collection, but this package is not installed or the plugin name is misspelled.

fix

Install the mdit-py-plugins package: pip install mdit-py-plugins. Verify the correct plugin name in your import statement, for example: from mdit_py_plugins.front_matter import front_matter_plugin.

error GitHub Flavored Markdown (GFM) features like tables or autolinking are not rendered correctly when using the 'gfm-like' preset. ↓

cause The `gfm-like` parser preset, while enabling GFM-like syntax, specifically requires the `linkify-it-py` package to be installed for linkification, which is not a default dependency of `markdown-it-py`.

fix

Install the linkify-it-py package, typically by installing markdown-it-py with the linkify extra: pip install markdown-it-py[linkify] or explicitly pip install linkify-it-py.

error AttributeError: 'MarkdownIt' object has no attribute 'rules' (or similar attribute for internal parser components) ↓

cause You are attempting to directly access or modify internal parser rule collections or methods (e.g., `md.parser.inline.rules`) that are not part of the public API, possibly stemming from attempts to port JavaScript `markdown-it` code without adapting to the Python API.

fix

Instead of direct manipulation, use the exposed MarkdownIt methods like .enable(), .disable(), or .use() for managing rules and extensions. For custom rule creation, follow the plugin development guidelines.

Warnings

breaking Dropped support for Python 3.8 and 3.9 in version 4.0.0. ↓

fix Upgrade your Python environment to version 3.10 or later.

breaking Updated parser to comply with CommonMark 0.31.2 and Markdown-It v14.1.0, which may affect parsing behavior. ↓

fix Review your Markdown content to ensure compatibility with the updated parsing rules.

deprecated The use of StateBase.srcCharCode is deprecated; replaced by StateBase.src. ↓

fix Update your code to use StateBase.src instead of StateBase.srcCharCode.

gotcha The linkify feature requires the optional linkify-it-py dependency. ↓

fix Install the optional dependency using pip install markdown-it-py[linkify].

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.16s 18.6M

3.10 slim (glibc) - - 0.14s 19M

3.11 alpine (musl) - - 0.27s 20.5M

3.11 slim (glibc) - - 0.22s 21M

3.12 alpine (musl) - - 0.22s 12.4M

3.12 slim (glibc) - - 0.23s 13M

3.13 alpine (musl) - - 0.20s 12.0M

3.13 slim (glibc) - - 0.20s 13M

3.9 alpine (musl) - - 0.13s 18.1M

3.9 slim (glibc) - - 0.11s 19M

Imports

MarkdownIt
wrong
```
from markdown_it_py import MarkdownIt
```
correct
```
from markdown_it import MarkdownIt
```
The correct import is from the markdown_it module, not markdown_it_py.

Quickstart verified last tested: 2026-04-23

This example demonstrates how to convert a Markdown string to HTML using markdown-it-py.

from markdown_it import MarkdownIt

md = MarkdownIt()
text = "# Hello World\n\nThis is a paragraph with **bold** and *italic* text."
html = md.render(text)
print(html)