Install & Compatibility
Where this runs
tested against v4.0.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 96.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.9s · import 0.000s · 98MB
100MB installed
● package 100MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
setup
✓ from myst_parser import setup
✗ import myst_parser
To quickly get started, add `myst_parser` to your Sphinx `conf.py` extensions list. This enables parsing of `.md` files as MyST Markdown. You can also configure various MyST extensions like `colon_fence` or `admonition` via `myst_enable_extensions` in `conf.py` or through frontmatter in individual documents.
# conf.py
extensions = [
"myst_parser",
"sphinx.ext.autodoc"
]
# Enable common MyST extensions
myst_enable_extensions = [
"colon_fence",
"deflist",
"fieldlist",
"html_admonition",
"html_image",
"linkify",
"replacements",
"smartquotes",
"strikethrough",
"substitution",
"tasklist"
]
# index.md
# MyST Project
This is some **MyST Markdown** content.
:::{note}
This is a MyST admonition.
:::
Debug
Known issues
breakingMyST-Parser v5.0.0 drops support for Python <3.11. Ensure your environment meets the new minimum requirement.fixUpgrade your Python environment to 3.11 or higher. If you need Python 3.10 support, use `myst-parser<5.0.0`.
affects: 5.0.0 and later
breakingMyST-Parser v5.0.0 significantly updates minimum Sphinx and Docutils versions. Old versions will not be compatible.fixUpgrade Sphinx to `>=8,<10` and Docutils to `>=0.20,<0.23`. If using an older Sphinx/Docutils, you must pin `myst-parser` to a compatible version (e.g., `<5.0.0` for Sphinx 7, Docutils 0.19).
affects: 5.0.0 and later
breakingThe underlying `markdown-it-py` parser was upgraded to `~=4.0` in v5.0.0 (from v3 in v2.0.0), potentially introducing subtle parsing behavior changes or requiring plugin updates.fixReview your MyST markdown for any edge cases, especially if you rely on specific `markdown-it-py` plugins or custom parser logic. Consult `markdown-it-py` v4 release notes for details.
affects: 5.0.0 and later
breakingVersions 4.0.0 also introduced breaking changes to minimum Python, Sphinx, and Docutils requirements.fixEnsure Python `>=3.10`, Sphinx `>=7,<9`, and Docutils `>=0.19,<0.22` are installed when using `myst-parser>=4.0.0,<5.0.0`.
affects: 4.0.0 - 4.x.x
gotchaDirect API functions like `to_html` or `to_docutils` are mainly for testing/development. For full Sphinx-specific features (e.g., cross-references, custom directives), use the Sphinx build process or explicitly load Sphinx-specific renderers with `in_sphinx_env`.fixFor comprehensive documentation generation, integrate MyST-Parser via the Sphinx `extensions` mechanism. For standalone parsing with Sphinx roles/directives, configure `in_sphinx_env=True` when initializing renderers.
affects: All versions
gotchaTo use fenced code blocks as Sphinx directives (e.g., for Mermaid diagrams or other renderers), you must explicitly enable `myst_fence_as_directive` in your `conf.py`.fixAdd `myst_fence_as_directive = ["directive_name"]` to your `conf.py`, where `directive_name` is the name of the directive (e.g., `mermaid`) you want to associate with fenced code blocks.
affects: 0.19.2 and later
gotchaThe test script `/script.py` encountered a `SyntaxError` on line 25 (e.g., `This is some **MyST Markdown** content.`), indicating the script itself contains invalid Python syntax or was executed incorrectly as a Python file.fixReview the `/script.py` file to ensure it contains valid Python syntax and is correctly configured to use the `myst-parser` library, rather than containing malformed Python code or attempting to execute raw MyST markdown as Python.
affects: All versions
gotchaAttempting to execute a MyST Markdown file directly with the Python interpreter will result in a `SyntaxError`, as MyST Markdown is not valid Python code. MyST-Parser is a library for parsing Markdown within a Python environment, not a standalone interpreter for Markdown files.fixEnsure MyST Markdown files are processed by `myst-parser` functions (e.g., `parser.parse()` or via Sphinx integration) from within a valid Python script, rather than being executed directly by the Python interpreter.
affects: All versions
Upgrade
Version history
5.1.0latest on PyPI · released May 13, 2026
Audit
Dependencies
pythonrequiredMinimum Python version required for MyST-Parser v5.0.0.
sphinxrequiredRequired for Sphinx integration.
docutilsrequiredCore dependency for parsing and rendering.
markdown-it-pyrequiredUnderlying CommonMark parser.