{"id":533,"library":"mistune","title":"Mistune Markdown Parser","description":"Mistune is a sane and fast Markdown parser for Python, offering various useful plugins and renderers. It is actively maintained, with the current version being 3.2.0, and receives regular updates to support newer Python versions and fix bugs.","status":"active","version":"3.2.0","language":"python","source_language":"en","source_url":"https://github.com/lepture/mistune","tags":["markdown","parser","html","renderer","plugins","fast"],"install":[{"cmd":"pip install mistune","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"The `mistune.html()` function is the recommended high-level entry point for converting Markdown to HTML with common features enabled by default (e.g., no HTML escape, strikethrough, table, footnote plugins).","symbol":"html","correct":"import mistune\nhtml_output = mistune.html(markdown_text)"},{"note":"`create_markdown()` is the preferred factory function for creating customizable Markdown instances with specific renderers and plugins, simplifying setup compared to manually instantiating `Markdown` and `HTMLRenderer`.","wrong":"from mistune import Markdown\nrenderer = mistune.HTMLRenderer()\nmarkdown = Markdown(renderer, plugins=['strikethrough'])","symbol":"create_markdown","correct":"from mistune import create_markdown\nmarkdown = create_markdown(plugins=['strikethrough'])\nhtml_output = markdown(markdown_text)"}],"quickstart":{"code":"import mistune\n\nmarkdown_text = \"\"\"\n# Hello, Mistune!\n\nThis is **bold** text and `code`.\n\n- Item 1\n- Item 2\n\"\"\"\n\nhtml_output = mistune.html(markdown_text)\nprint(html_output)","lang":"python","description":"This quickstart demonstrates the simplest way to convert Markdown text to HTML using the `mistune.html()` function, which provides a default setup with many common features enabled."},"warnings":[{"fix":"Refer to the official 'Upgrade Guide' for detailed changes. Parameter signatures for custom renderer methods and directive handling have been altered. For instance, `RstDirective` was renamed to `RSTDirective`.","message":"Mistune v3 introduced significant breaking changes compared to v2, particularly in custom renderer methods' parameters and the redesign of directives. Migrating existing code, especially custom plugins or renderers, will require updates.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If using `create_markdown()`, explicitly set `escape=False` in its parameters if you want raw HTML to be rendered directly: `mistune.create_markdown(escape=False)`. Always be mindful of potential XSS vulnerabilities when disabling HTML escaping for untrusted input.","message":"The default behavior for HTML escaping differs between `mistune.html()` and `mistune.create_markdown()`. `mistune.html()` does not escape raw HTML tags by default, while `mistune.create_markdown()` (without `escape=False`) *does* escape HTML.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Initialize a Markdown instance once using `markdown = mistune.create_markdown(...)` and then call `markdown(text)` for subsequent conversions.","message":"While a global `mistune.markdown()` function exists, for performance-critical applications or when using custom configurations and plugins, it is recommended to create and reuse a `Markdown` instance (e.g., via `mistune.create_markdown()`) rather than calling the global function repeatedly.","severity":"gotcha","affected_versions":"All v3 versions"},{"fix":"Upgrade to `mistune>=3.0.2` to resolve potential `RecursionError` issues with list parsing.","message":"Versions of Mistune v3 prior to 3.0.2 experienced a `RecursionError` when parsing complex lists.","severity":"gotcha","affected_versions":"<3.0.2"}],"env_vars":null,"last_verified":"2026-05-12T14:43:50.507Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"If this error originates from a dependent package, try updating that package to a version compatible with `mistune` v3.2.0. If no compatible version exists, you might need to downgrade `mistune` to `mistune<2` (e.g., `pip install \"mistune<2\"`) to match the dependent package's requirements. If you are directly using `mistune`, refactor your code to use the modern `mistune` v3.x API for custom parsers and renderers, which involves `mistune.create_markdown` and custom renderer classes or plugins.","cause":"This error frequently occurs when a project or a dependency (like `nbconvert` or `m2r`) is written for `mistune` v0.x or v1.x, but `mistune` v2.x or v3.x (like 3.2.0) is installed, as the internal API, including `BlockGrammar`, was completely redesigned in `mistune` v2 and is no longer directly exposed.","error":"AttributeError: module 'mistune' has no attribute 'BlockGrammar'"},{"fix":"Change the import statement from `from mistune.renderers import AstRenderer` to `from mistune import AstRenderer` (or `HTMLRenderer`). Alternatively, use `markdown = mistune.create_markdown(renderer=\"ast\")` for AST output.","cause":"In `mistune` v3.x (including 3.2.0), `AstRenderer` (and `HTMLRenderer`) are no longer imported from `mistune.renderers`. Instead, they are directly available under the `mistune` namespace or by using the `renderer` argument in `mistune.create_markdown`.","error":"ImportError: cannot import name 'AstRenderer' from 'mistune.renderers'"},{"fix":"Install the library using pip: `pip install mistune`.","cause":"The `mistune` library is not installed in the current Python environment or is not accessible on the `sys.path`.","error":"ModuleNotFoundError: No module named 'mistune'"},{"fix":"Ensure you are using `mistune` v3.x. For built-in plugins, pass their names as strings to `mistune.create_markdown`: `markdown = mistune.create_markdown(plugins=['strikethrough', 'table'])`. If you need to customize or create a plugin, you would import its base components, e.g., `from mistune.plugins import strikethrough`.","cause":"This error can occur if you are trying to import plugins directly from `mistune.plugins` in an older `mistune` version (pre-v2) where they might not have existed, or if there's a problem with how plugins are accessed in a v3 installation. In `mistune` v3.2.0, standard plugins are typically used by passing their names as strings to `mistune.create_markdown(plugins=[...])` or by importing specific plugin functions from `mistune.plugins` for custom configurations.","error":"ModuleNotFoundError: No module named 'mistune.plugins'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":2.7,"disk_size":"18.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.7,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":1.9,"disk_size":"20.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":1.9,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":1.6,"disk_size":"12.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.6,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":1.7,"disk_size":"11.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.5,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"18.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}