Install & Compatibility
Where this runs
tested against v1.0.2 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.998s · 147MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 9.4s · import 0.947s · 148MB
171MB installed
● package 171MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Cytoscape
✓ import dash_cytoscape as cyto
from dash import Dash, html
✗ import dash_cytoscape
from dash import Dash, html # then use dash_cytoscape.Cytoscape
The convention is to import `dash_cytoscape` as `cyto` for brevity and consistency with examples.
load_extra_layouts
✓ import dash_cytoscape as cyto
cyto.load_extra_layouts()
Required to enable external layouts (e.g., COSE-Bilkent, FCose) and SVG image generation.
This quickstart creates a simple Dash application displaying a two-node, one-edge graph. It demonstrates basic `Cytoscape` component usage with `elements`, `layout`, and `stylesheet` properties. Remember to run `pip install dash` first if not already installed.
from dash import Dash, html
import dash_cytoscape as cyto
app = Dash(__name__)
app.layout = html.Div([
cyto.Cytoscape(
id='cytoscape-two-nodes',
layout={'name': 'preset'},
style={'width': '100%', 'height': '400px'},
elements=[
{'data': {'id': 'one', 'label': 'Node 1'}, 'position': {'x': 75, 'y': 75}},
{'data': {'id': 'two', 'label': 'Node 2'}, 'position': {'x': 200, 'y': 200}},
{'data': {'source': 'one', 'target': 'two', 'label': 'Node 1 to 2'}}
],
stylesheet=[
{
'selector': 'node',
'style': {
'background-color': '#BFD7B5',
'label': 'data(label)'
}
},
{
'selector': 'edge',
'style': {
'line-color': '#A3C4BC',
'label': 'data(label)'
}
}
]
)
])
if __name__ == '__main__':
app.run_server(debug=True)
Debug
Known issues
breakingSupport for Python 3.7 and below was dropped in `dash-cytoscape` version 1.0.0. The new minimum Python version is 3.8.fixUpgrade Python environment to 3.8 or newer. Use `pip install 'dash-cytoscape<1.0.0'` for older Python versions.
affects: >=1.0.0
gotchaWhen dynamically updating the graph with new `elements` (nodes and edges), ensure that node and edge IDs are unique. Reusing IDs can lead to networks fusing or unexpected behavior due to the underlying Cytoscape.js library not properly cleaning the object.fixGenerate unique IDs for all nodes and edges across different states or updates of the graph, for example, by adding a prefix or using UUIDs.
affects: All versions
gotchaCallbacks must be defined *before* `app.run_server()`. If a `@app.callback` decorator and its associated function are placed after `app.run_server()`, the callback will not be registered and will not fire.fixEnsure all `@app.callback` definitions and their corresponding functions are placed in the main script *before* the `if __name__ == '__main__': app.run_server(debug=True)` block.
affects: All versions
gotchaWhen modifying `elements` inside a callback, you should return a *new* list/dictionary of elements rather than mutating the original object passed as `State`. Direct mutation of objects received via `State` can lead to update cycles being broken or inconsistent behavior.fixCreate a copy of the `elements` list/dictionary (`new_elements = elements[:]` or `new_elements = list(elements)`) and modify the copy before returning it from the callback.
affects: All versions
deprecatedThe `dash_html_components` and `dash_core_components` imports were removed from `install_requires` in older versions. While still usable, components like `html.Div` are now typically imported directly from `dash`.fixUpdate imports from `import dash_html_components as html` to `from dash import html` (and similarly for `dcc`).
affects: >=0.1.1 (and later)
Errors
Common errors & fixes
Dash Cytoscape callbacks not firing
The callback function was defined after `app.run_server()` or `app.run()` in the script.
fixMove all `@app.callback` definitions and their functions to appear before the `if __name__ == '__main__': app.run_server(debug=True)` block.
TypeError: Cannot read properties of undefined (reading 'length') when elements is not specified
The `elements` property of the `cyto.Cytoscape` component was not provided or was `None`.
fixEnsure the `elements` property is always a list of nodes and edges, even if empty (`elements=[]`). This issue was fixed in `dash-cytoscape` version 0.1.1 but can still occur with incorrect usage.
Graph showing incorrect connections or overlapping nodes after update, networks fused together based on common ID
When updating the `elements` property, new nodes or edges were introduced with IDs that already existed in the previous graph state. The underlying Cytoscape.js library can conflate elements with identical IDs, leading to unexpected graph structures.
fixEnsure all node and edge IDs are unique across all elements present in the graph at any given time, especially when dynamically modifying or replacing the graph content.
Dash app crashes without error message or restarts frequently when using Cytoscape component.
This can sometimes occur with complex or very large graphs, potentially related to memory usage or issues within the underlying JavaScript rendering. It might also be related to specific environment configurations or resource limitations.
fixTry simplifying the graph, optimizing `stylesheet` definitions, or reducing the number of `elements`. Consider restarting the Python environment or the operating system. Check browser developer console for any JavaScript errors. For very large graphs, consider server-side rendering or pagination if applicable.
Upgrade
Version history
1.0.2latest on PyPI · released Jul 15, 2024
Audit
Dependencies
dashrequiredCore Dash framework dependency for component integration and callbacks.
dash-leafletoptionalRequired for the CyLeaflet all-in-one component, which overlays network graphs on Leaflet maps.