Install & Compatibility
Where this runs
tested against v0.0.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.920 runs
installs and imports cleanly · install 0.0s · import 0.058s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.050s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chart
✓ from mermaid_builder.flowchart import Chart
Commonly used for creating flowchart diagrams.
Node
✓ from mermaid_builder.flowchart import Node
Used to define nodes within a flowchart.
This quickstart demonstrates how to create a simple flowchart using `mermaid-builder`. It initializes a `Chart`, adds `Node` objects, defines links between them, and then renders the MermaidJS markdown string. The generated string can be pasted into a MermaidJS compatible viewer or Markdown file to visualize the diagram.
from mermaid_builder.flowchart import Chart, Node
# Create a new flowchart
chart = Chart("MyCompanyHierarchy", direction="TD") # Top Down direction
# Add nodes
node_a = Node("Company A")
node_b = Node("Company B")
node_c = Node("Company C")
node_d = Node("Company D")
chart.add_node(node_a)
chart.add_node(node_b)
chart.add_node(node_c)
chart.add_node(node_d)
# Define relationships
chart.link(node_a, node_b)
chart.link(node_a, node_c)
chart.link(node_b, node_d)
# Generate the MermaidJS markup
mermaid_markup = chart.render()
print(mermaid_markup)
# To view this diagram, paste the output into a MermaidJS editor (e.g., mermaid.live)
# or use in a Markdown file that supports Mermaid rendering (e.g., GitHub).
Debug
Known issues
breakingThe library is in early development (version 0.0.3) and explicitly marked as 'Work in progress'. This means its API is subject to frequent changes, and backward compatibility is not guaranteed between minor versions.fixRefer to the latest GitHub README and PyPI project description before upgrading. Pin exact versions in your `requirements.txt`.
affects: <1.0.0
gotchaThis library generates MermaidJS *markup*, but does not render the diagrams itself. To visualize the diagrams, you will need a separate Mermaid.js rendering engine (e.g., a web browser with `mermaid.js` loaded, a Markdown viewer like GitHub, or the `mmdc` CLI tool which requires Node.js).fixEnsure your environment has a suitable MermaidJS renderer available to consume the generated markup. For command-line rendering, consider installing `mmdc` (`npm install -g @mermaid-js/mermaid-cli`).
affects: All
gotchaThe PyPI project description lists several 'Next tasks' such as 'styling for flowchart (adding classes and styles)' and 'class diagrams'. This indicates that certain advanced MermaidJS features might not yet be fully implemented or supported by `mermaid-builder`.fixCheck the project's GitHub repository or documentation for the current status of feature implementation. Contribute or open an issue if a desired feature is missing.
affects: <1.0.0
gotchaWhen MermaidJS diagrams are rendered in applications with dynamic theming (e.g., dark/light modes in some markdown editors), custom colors defined in the generated markup might be unexpectedly inverted or altered due to CSS filters applied by the rendering environment.fixIf precise color control is critical across themes, you may need to implement custom CSS overrides in your rendering environment or experiment with neutral color palettes that adapt better to inversion filters. Consult the Mermaid.js documentation on theming.
affects: All (Mermaid.js rendering issue)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mermaid_builder'
The `mermaid-builder` package was not installed or was installed in a different Python environment, or there's a typo in the import statement.
fixEnsure the library is installed using `pip install mermaid-builder` and that the Python environment where the script is run has access to this installation. The correct import statement uses underscores, not hyphens: `from mermaid_builder.diagram import Flowchart`.
AttributeError: module 'mermaid_builder' has no attribute 'Flowchart'
The `Flowchart` class (or other diagram components) is not directly available under the top-level `mermaid_builder` module. It resides within submodules like `mermaid_builder.diagram`, `mermaid_builder.node`, or `mermaid_builder.link`.
fixImport the specific component from its correct submodule, for example: `from mermaid_builder.diagram import Flowchart`.
TypeError: Flowchart.__init__() missing 1 required positional argument: 'title'
The `Flowchart` constructor (and potentially other diagram elements) requires a `title` argument which was not provided during instantiation.
fixProvide the mandatory `title` argument when creating a `Flowchart` instance: `chart = Flowchart(title='My Diagram Title')`.
NameError: name 'Node' is not defined
The `Node` class was used without being explicitly imported from its respective submodule within `mermaid_builder`.
fixImport the `Node` class (or any other component) from its correct location: `from mermaid_builder.node import Node`.
Upgrade
Version history
0.0.3latest on PyPI · released Jun 14, 2024
Audit
Dependencies
No dependency data recorded yet.