PyVis — Interactive Network Visualization for Python

PyVis is a Python library for creating and visualizing interactive network graphs, built on top of the vis.js JavaScript library. This edition adds type-safe configuration, Shiny for Python integration, security hardening, and performance optimizations over the upstream project.

Features

• Interactive visualizations — Pan, zoom, drag nodes, hover tooltips, all in the browser
• NetworkX integration — Convert NetworkX graphs directly with from_nx()
• Type-safe options — 44 Python dataclasses covering 100% of the vis-network configuration surface
• Shiny for Python — Full bidirectional integration with event handling, viewport control, and live data updates
• Multiple physics engines — Barnes-Hut, Force Atlas 2, repulsion, and hierarchical repulsion
• Jupyter support — Render networks inline in Jupyter notebooks
• Security hardened — Jinja2 autoescape prevents XSS, input validation on file operations
• Runtime validation — Type-safe options with __post_init__ checks for opacity, font alignment, and more

Installation

Requires Python >= 3.10

pip install pyvis-optimized

With optional dependencies:

pip install pyvis-optimized[shiny]     # Shiny for Python integration
pip install pyvis-optimized[notebook]  # Jupyter/IPython notebook support
pip install pyvis-optimized[dev]       # Development tools (pytest, black, mypy)
pip install pyvis-optimized[test]      # Test dependencies (pytest, playwright)
pip install pyvis-optimized[all]       # Everything

The conda package always includes IPython; on PyPI it is the notebook extra.

Or from source:

pip install .

Dependencies

Package	Purpose
networkx >= 1.11	Graph data structures
jinja2 >= 2.9.6	HTML template rendering
jsonpickle >= 1.4.1	JSON serialization

Optional: ipython >= 5.3.0 (pyvis-optimized[notebook]), shiny >= 1.0 and htmltools (pyvis-optimized[shiny])

Quick Start

from pyvis.network import Network

net = Network()
net.add_node(1, label="Node 1", color="#97c2fc")
net.add_node(2, label="Node 2", color="#ffcc00")
net.add_edge(1, 2, width=2)
net.show("basic.html", notebook=False)

From NetworkX

import networkx as nx
from pyvis.network import Network

G = nx.karate_club_graph()
net = Network()
net.from_nx(G)
net.show("karate.html", notebook=False)

Type-Safe Options

Configure every aspect of your network visualization with Python dataclasses that provide IDE autocompletion and type checking:

from pyvis.network import Network
from pyvis.types import (
    NetworkOptions, NodeOptions, EdgeOptions, PhysicsOptions,
    BarnesHut, LayoutOptions, InteractionOptions, Font
)

options = NetworkOptions(
    nodes=NodeOptions(
        shape="dot",
        font=Font(size=14, color="#333333"),
    ),
    edges=EdgeOptions(
        smooth=True,
        color="#848484",
    ),
    physics=PhysicsOptions(
        solver="barnesHut",
        barnesHut=BarnesHut(gravitationalConstant=-3000),
    ),
    interaction=InteractionOptions(
        hover=True,
        tooltipDelay=200,
    ),
)

net = Network()
net.set_options(options)
net.add_node(1, label="A")
net.add_node(2, label="B")
net.add_edge(1, 2)
net.show("typed.html", notebook=False)

The pyvis.types module provides 44 dataclasses covering nodes, edges, physics, layout, interaction, configuration, and manipulation — the full vis-network API surface.

Shiny for Python Integration

Build interactive web applications with bidirectional communication between Python and the network:

from shiny import App, ui, render, reactive
from pyvis.network import Network
from pyvis.shiny import (
    output_pyvis_network, render_pyvis_network,
    PyVisNetworkController
)

app_ui = ui.page_fluid(
    output_pyvis_network("network", height="600px"),
    ui.input_action_button("fit", "Fit to View"),
    ui.output_text_verbatim("selected")
)

def server(input, output, session):
    ctrl = PyVisNetworkController("network", session)

    @render_pyvis_network
    def network():
        net = Network(cdn_resources="remote")
        net.add_node(1, label="Node 1")
        net.add_node(2, label="Node 2")
        net.add_edge(1, 2)
        return net

    @reactive.effect
    @reactive.event(input.fit)
    def _():
        ctrl.fit()

    @render.text
    def selected():
        event = input.network_selectNode()
        return f"Selected: {event['nodeId']}" if event else "Click a node"

app = App(app_ui, server)

Shiny Capabilities

Category	Functions
Events	click, doubleClick, selectNode, selectEdge, hoverNode, dragStart, zoom, stabilized, and more
Selection	select_nodes, select_edges, unselect_all
Viewport	fit, focus, move_to
Physics	start_physics, stop_physics, stabilize
Data	add/update/remove nodes and edges, get_positions, get_all_data
Clustering	cluster_by_connection, cluster_by_hubsize, open_cluster
Theming	set_options, set_theme

See the Shiny Integration Guide for complete documentation.

Documentation

• API Reference — Complete reference for Network class, typed options (44 dataclasses), Shiny integration, and all public methods
• Shiny Integration Guide — Detailed guide for using PyVis with Shiny for Python
• Releasing — How a release is cut and published to PyPI and anaconda.org, and how to retry a failed one

Testing

pytest pyvis/tests/ --ignore=pyvis/tests/test_html.py -v

That command runs 474 tests covering core network operations, typed options, Shiny integration, security, error handling, and regression tests for edge cases. The full suite is 495 (run pytest --co for the current count); the extra 21 are the Playwright browser tests in test_html.py, test_bindings_js.py, and test_shiny_e2e.py, which need pip install pyvis-optimized[test] followed by python -m playwright install chromium.

Versioning

Version is managed from a single source of truth: pyvis/_version.py. Use the bump script for releases:

python auto_version.py          # bump from conventional commits, update CHANGELOG, commit, tag
python auto_version.py minor    # explicit bump; CHANGELOG still built from commits
python auto_version.py --no-commit   # dry run: update files only

Project Structure

pyvis/
    network.py          # Main Network class
    node.py             # Node representation
    edge.py             # Edge representation
    _version.py         # Single source of truth for version
    utils.py            # Validation utilities
    types/              # Type-safe dataclass options (44 classes)
    shiny/              # Shiny for Python integration
        wrapper.py      # Controller, standalone functions, rendering
        bindings.js     # JavaScript binding for vis-network
    tests/              # 495 tests across 29 modules (see `pytest --co` for current count)
auto_version.py         # Version bump + changelog + tag script

License

BSD License. Based on WestHealth/pyvis.