---
id: markdown-exec
version: "1.12.3"
license: ISC
license_treatment: permissive
maintenance: active
---

# markdown-exec — Utilities to execute code blocks in Markdown files.

License: permissive · Maintenance: active · Downloads: 975.4K/mo

## What it is and what it does

Markdown Exec is a Markdown extension that transforms code blocks into executable snippets. When you mark a code block with `exec="on"`, the extension runs that code and injects the output back into the document in place of the original block. It works as a plugin for MkDocs or as a standalone Markdown extension, integrating with pymdown-extensions' SuperFences to handle multiple languages including Python, bash, and console sessions.

The package is designed for documentation workflows where you want code examples to stay synchronized with their actual output—write a Python snippet that generates HTML or a bash command that lists files, and the rendered documentation automatically shows what that code produces. It supports optional ANSI color rendering for terminal output via the `ansi` extra, and can be configured to expect specific exit codes or handle errors gracefully.

Use it for:

- Auto-generate API documentation by executing code examples that produce formatted output
- Keep shell command examples in docs synchronized with their real output
- Build documentation sites where Python snippets compute and display results
- Create reproducible tutorials where code blocks run during the build and embed their results
- Generate tables or formatted lists in Markdown by executing Python code that produces them

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Executes code blocks embedded in Markdown files and replaces them with their output, supporting Python, bash, and other languages with optional ANSI color rendering.

Yes, if you maintain documentation with code examples that need to stay current. The low install friction, active maintenance, permissive license, and lack of known vulnerabilities make it safe to adopt. Install with caution only if your documentation build process runs untrusted code, since execution happens at build time—otherwise it's a straightforward win for keeping examples accurate.

## Install

pip install markdown-exec
uv add markdown-exec
poetry add markdown-exec

## Installing markdown-exec

Before you install: Low friction: pure Python wheel with a single runtime dependency (pymdown-extensions). Actively maintained with recent releases; last commit 2026-07-08. Requires Python 3.10 or later.

License in practice: ISC license is permissive and imposes minimal restrictions; suitable for both open-source and commercial use without copyleft obligations.

Quickstart:

pip install markdown-exec

from markdown import Markdown
from markdown_exec import formatter, validator

Markdown(
    extensions=["pymdownx.superfences"],
    extension_configs={
        "pymdownx.superfences": {
            "custom_fences": [{
                "name": "python",
                "class": "python",
                "validator": validator,
                "format": formatter,
            }]
        }
    }
)

Requires Python 3.10 or later; pymdown-extensions must be installed as a runtime dependency.

Verify before relying:

- Security implications of executing arbitrary code blocks during documentation builds
- Performance impact when processing large numbers of code blocks or long-running scripts
- Whether pyodide support is fully functional or still experimental

## Package facts

- License: ISC (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 975.4K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

execute code in markdown, markdown code block execution, dynamic markdown generation, mkdocs code execution, markdown to html with code output, embedded script execution markdown, markdown documentation automation, mkdocs-plugin, documentation-automation, code-execution

[View on SkillFed](https://skillfed.io/packages/markdown-exec) · [View on PyPI](https://pypi.org/project/markdown-exec/)