Interactive Cytoscape Widget for Jupyter

1.3.3 · active · verified Fri Apr 17

ipycytoscape is a Python library that provides a Cytoscape widget for Jupyter notebooks and JupyterLab environments. It allows users to visualize and interact with complex networks directly within their Jupyter workflows, leveraging the powerful rendering capabilities of Cytoscape.js. The current version is 1.3.3, with minor releases occurring every few months for bug fixes and compatibility updates.

Common errors

```
Widget not found. This usually happens when the widgets JavaScript hasn't been run.
```
cause The Jupyter environment (JupyterLab or classic Notebook) has not correctly loaded the ipycytoscape frontend extension.

fix For JupyterLab 3+, ensure `ipycytoscape>=1.2.0` is installed. No manual build should be needed. For classic Notebook, try `jupyter nbextension enable --py --sys-prefix ipycytoscape`. Restart your kernel and browser.
```
TraitError: The 'layout' trait of a CytoscapeWidget instance must be a dict or None, but a value of type <class 'str'> was specified.
```
cause You passed a string directly to `cy.layout` instead of using the `set_layout` method, or the `set_layout` method was used with an invalid parameter type.

fix Use the `set_layout` method with the `name` parameter, e.g., `cy.set_layout(name='cola')`. If you need custom layout options, provide a dictionary: `cy.set_layout(name='cose', options={'padding': 10})`.
```
ModuleNotFoundError: No module named 'ipycytoscape'
```
cause The `ipycytoscape` package is not installed in the Python environment where Jupyter is running.

fix Install the package: `pip install ipycytoscape`. Ensure you are installing into the correct Python environment if you use virtual environments or conda environments.

Warnings

breaking Version 1.2.0 significantly changed how ipycytoscape integrates with JupyterLab. Prior to 1.2.0, an explicit `jupyter lab build` step and Node.js were often required. Version 1.2.0+ no longer requires these for JupyterLab 3 and above.
Fix: Ensure you are using `ipycytoscape>=1.2.0` for JupyterLab 3+ compatibility without a build step. If upgrading from an older version, remove any manual `jupyter lab build` steps from your workflow. Consider `pip install --upgrade ipycytoscape`.
gotcha Graphs may not display properly (nodes overlapping at the center) if a layout is not explicitly set using `cy.set_layout()`. Cytoscape.js requires a layout algorithm to arrange nodes and edges.
Fix: Always call `cy.set_layout(name='some_layout_name')` after adding graph data to the widget. Common layout names include 'cola', 'cose', 'grid', 'circle', 'random'.
gotcha When using `ipycytoscape` in classic Jupyter Notebook (not JupyterLab), you might need to ensure the nbextension is enabled, especially if the widget does not render.
Fix: Run `jupyter nbextension enable --py --sys-prefix ipycytoscape` from your terminal if widgets fail to load in classic Jupyter Notebook.

Install

pip install ipycytoscape Install ipycytoscape

Imports

CytoscapeWidget

from ipycytoscape import CytoscapeWidget

Quickstart

This quickstart demonstrates how to create a Cytoscape widget, populate it with data from a NetworkX graph, apply a layout, and display it in a Jupyter environment. The `set_layout()` call is essential for proper rendering.

import ipycytoscape
import networkx as nx

# Create a Cytoscape widget instance
cy = ipycytoscape.CytoscapeWidget()

# Create a simple graph using NetworkX
G = nx.Graph()
G.add_edge('A', 'B')
G.add_edge('B', 'C')
G.add_node('D')

# Add the graph data to the widget
cy.graph.add_graph_from_networkx(G, directed=False)

# Set a layout; this is crucial for the graph to display properly
cy.set_layout(name='cose') # Other options: 'cola', 'grid', 'circle', etc.

# Display the widget
cy

view raw JSON →