{"id":9935,"library":"mermaid-py","title":"mermaid-py","description":"`mermaid-py` is a Python interface for the popular `mermaid-js` library, simplifying the creation and rendering of diagrams directly from Python code. It currently targets the latest `Mermaid.js v10+` and provides methods to output diagrams as HTML, JSON, or images. The current version is 0.8.4, with releases typically following major Mermaid.js updates or API improvements.","status":"active","version":"0.8.4","language":"en","source_language":"en","source_url":"https://github.com/leewohlbold/mermaid-py","tags":["mermaid","diagrams","visualization","markdown","flowchart","sequence-diagram"],"install":[{"cmd":"pip install mermaid-py","lang":"bash","label":"Install mermaid-py"}],"dependencies":[],"imports":[{"note":"The package name is `mermaid-py`, but the top-level module to import from is `mermaid`.","wrong":"from mermaid_py import Mermaid","symbol":"Mermaid","correct":"from mermaid import Mermaid"}],"quickstart":{"code":"from mermaid import Mermaid\nimport os\n\n# Define a Mermaid diagram using its text syntax\ngraph_definition = \"\"\"\ngraph TD;\n    A[Start]-->B{Process Data};\n    B-->C[End];\n\"\"\"\n\n# Create a Mermaid object\ndiagram = Mermaid(graph_definition)\n\n# Get the HTML representation to embed or display\nhtml_output = diagram.to_html()\nprint(f\"HTML output starts with: {html_output[:50]}...\")\n\n# Or get the JSON representation\njson_output = diagram.to_json()\nprint(f\"JSON output (first 50 chars): {json_output[:50]}...\")\n\n# To generate an image, you would typically need Playwright installed and configured.\n# Example (requires 'pip install playwright' and 'playwright install chromium'):\n# if os.environ.get('MERMAID_ENABLE_IMAGE_TEST', 'false').lower() == 'true':\n#     try:\n#         image_data = diagram.to_image()\n#         print(f\"Generated image data (bytes length): {len(image_data)}\")\n#     except Exception as e:\n#         print(f\"Could not generate image (requires Playwright setup): {e}\")","lang":"python","description":"This quickstart demonstrates how to define a Mermaid diagram string, create a `Mermaid` object, and retrieve its HTML and JSON representations. Image generation is commented out as it requires additional external dependencies (Playwright) to be installed and configured."},"warnings":[{"fix":"Refer to the `mermaid-py` v0.8.0+ documentation for updated API usage, especially for `Mermaid` class instantiation and rendering methods. The `render()` method was removed.","message":"Major rewrite in `v0.8.0` removed async dependencies and simplified the API. If you were using `mermaid-py` directly before this version, expect significant breaking changes to import paths and method signatures.","severity":"breaking","affected_versions":"<0.8.0"},{"fix":"Ensure your Mermaid diagram definitions adhere to `Mermaid.js v10+` syntax. Consult the official `Mermaid.js` documentation for valid syntax.","message":"`mermaid-py` targets `Mermaid.js v10+`. Diagrams using syntax or features from older `Mermaid.js` versions might not render as expected or may fail.","severity":"gotcha","affected_versions":"all"},{"fix":"Install `playwright` (e.g., `pip install playwright`) and then run `playwright install chromium` to enable image rendering functionality.","message":"Generating images with `diagram.to_image()` requires additional setup, typically involving a headless browser (like Chromium) and its associated drivers via the `playwright` library.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from mermaid_py import Mermaid` to `from mermaid import Mermaid`.","cause":"The Python package is `mermaid-py`, but the top-level module to import from is `mermaid`.","error":"ModuleNotFoundError: No module named 'mermaid_py'"},{"fix":"`mermaid-py` v0.8.0+ no longer has a `render()` method. Use `to_html()`, `to_json()`, or `to_image()` on the `Mermaid` object directly to get the desired output.","cause":"Attempting to use an old `render()` method that was removed in the `v0.8.0` rewrite.","error":"AttributeError: 'Mermaid' object has no attribute 'render'"},{"fix":"Review your diagram string for typos, incorrect keywords, or improper structure. Refer to the official `Mermaid.js` documentation for correct syntax for your diagram type (e.g., graph, flowchart, sequence).","cause":"The provided Mermaid diagram definition has invalid syntax according to `Mermaid.js` or contains unsupported features for the targeted `Mermaid.js v10+`.","error":"MermaidParseError: Syntax error in diagram (or similar rendering/parsing error)"}]}