Install & Compatibility
Where this runs
tested against v1.12.3 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 34.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.4s · import 0.000s · 36MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
formatter
✓ from markdown_exec import formatter
✗ from markdown_exec import formatter, validator
validator
✓ from markdown_exec import validator
✗ from markdown_exec import formatter, validator
To quickly get started, create an `mkdocs.yml` file and a Markdown file (e.g., `docs/index.md`). Enable the `markdown-exec` plugin and `pymdownx.superfences` extension in your `mkdocs.yml`. Then, add a code block with `exec="on"` in your Markdown file. The example illustrates the structure for MkDocs integration, which is the recommended approach.
import os
# mkdocs.yml configuration example
# plugins:
# - search
# - markdown-exec
# markdown_extensions:
# - pymdownx.superfences
# Example Markdown content (e.g., in docs/index.md)
markdown_content = '''
# My Executable Documentation
This is a simple example of markdown-exec in action.
```python exec="on"
import sys
print(f"Hello from Python {sys.version.split(' ')}!")
```
'''
# To simulate execution without a full MkDocs setup, one would typically process this
# via the Markdown library with the markdown-exec extension enabled.
# However, the primary intended use is within MkDocs.
# For a true quickstart, an MkDocs project is implicitly assumed.
# This example is illustrative of the Markdown content.
# To make it runnable for an agent, assume an MkDocs build process:
# 1. Create a dummy mkdocs.yml (if not present)
# 2. Create a dummy docs/index.md with the content above
# 3. Run `mkdocs build` or `mkdocs serve`
# This Python snippet shows how the markdown content looks, not how to run it directly in Python for output capture.
# The actual execution happens via the Markdown extension or MkDocs plugin.
markdown-exec --version
Debug
Known issues
breakingSupport for Python 3.8 was dropped in version 1.10.0. Users on Python 3.8 or older must upgrade their Python environment or remain on an older version of markdown-exec.fixUpgrade Python to 3.9 or higher.
affects: >=1.10.0
gotchaWhen using the `pyodide` fence or other fences requiring asset inclusion, configuring `pymdownx.superfences` directly (without the MkDocs plugin) may require manual inclusion of assets (CSS/JS) for proper rendering. The MkDocs plugin handles this automatically.fixEnable markdown-exec as an MkDocs plugin (recommended) or manually include required assets if configuring `pymdownx.superfences` custom fences directly.
affects: All versions
gotchaIf `pymdownx.superfences` is not enabled in your Markdown extensions configuration, `markdown-exec` will error out early. This is a common oversight when setting up the library.fixEnsure `pymdownx.superfences` is listed in your `markdown_extensions` in `mkdocs.yml` or passed to `markdown.Markdown` when used programmatically.
affects: >=1.11.0
gotchaOutput escaping for strings printed directly was improved in versions 1.10.2 and 1.10.3 to address display issues and potential vulnerabilities. Older versions might render unescaped output.fixUpgrade to markdown-exec 1.10.3 or newer to ensure proper output escaping.
affects: <1.10.3
gotchaWhen using `markdown-exec` with `Material for MkDocs` and `source='tabbed-left'` (or `tabbed-right`), code annotations placed immediately after the code block may break due to the generated tab structure. The annotation logic in Material for MkDocs expects the list to be directly after the code block.fixAvoid using code annotations immediately after code blocks that employ `source='tabbed-left'` (or `tabbed-right`) or consider alternative rendering options.
affects: All versions with Material for MkDocs and tabbed source
Upgrade
Version history
1.12.3latest on PyPI · released Jul 7, 2026
Audit
Dependencies
Pymdown-ExtensionsrequiredRequired for configuring custom code fences, specifically `pymdownx.superfences`.
pygments-ansi-coloroptionalOptional, provides ANSI color rendering support when installing with the `[ansi]` extra.
MkDocsoptionalHighly recommended for integrating markdown-exec as a plugin or extension in documentation sites.