sphinx "ERROR: Failed to load extension 'myst_parser'" build failed
Fixes Sphinx builds that abort because the myst_parser extension cannot be loaded. Use when the error names myst_parser as the failed extension. Not for autodoc or theme load failures.
TL;DR
Install the myst-parser package into the environment running the build and spell the extension name exactly myst_parser in conf.py. The package name on PyPI uses a hyphen while the extension module uses an underscore.
Error
ERROR: Failed to load extension 'myst_parser'Steps
- Check whether the package is installed in the build environment:
pip show myst-parser. Expected: either version info or "not installed", which tells you which fix applies. - Install it with
pip install myst-parser, pinning a version compatible with your Sphinx release (myst-parser 2.x pairs with Sphinx 7+, 3.x with Sphinx 8). Expected: pip reports a successful install. - Open conf.py and confirm the extensions list contains the string
myst_parserexactly, notmyst-parserormyst. Expected: the underscore spelling is present. - Rebuild with
sphinx-build -b html docs docs/_build. Expected: the extension loads and Markdown sources parse.
When to use
- The build fails naming myst_parser as the unloadable extension
- You added Markdown sources to a previously RST-only project
- CI or Read the Docs fails while the local build works
When not to use
- The extension loads but Markdown renders wrong (a myst configuration issue, not a load failure)
- You meant to use recommonmark, which is a different package and extension name
- The failure names a different extension
Tool compatibility
Sphinx 7.x/8.x with myst-parser 2.x/3.x. If you are stuck on Sphinx 5 or 6, use myst-parser 1.x.
Variant phrasings
Sphinx reports "No module named 'myst_parser'"
Same root cause: the package is missing from the build environment. Install it.
extension loads locally but not on Read the Docs
Add myst-parser to the docs requirements file that Read the Docs installs; the local environment is irrelevant to the hosted build.
Why it happens
The PyPI distribution name (myst-parser) differs from the importable module name (myst_parser), so installs and config edits get out of sync. Clean CI environments expose the missing dependency that a developer's laptop hides.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_1v9zHheJYOUkMHiuGPVeaQ