Ripple

Reactive notebook execution in Jupyter

Run a cell, and Ripple automatically re-runs every cell that depends on it. No more hunting for stale outputs or manually replaying half the notebook. Install it, and reactivity is on from the start.

Highlights

• Always in sync — change a variable, downstream cells re-run automatically
• Visual dependency map — colored borders show upstream (blue), downstream (green), stale (amber), and conflict/cycle (red) cells at a glance
• Zero migration — pip install, and it just works. Standard ipykernel, your existing .ipynb files, no custom kernel or new notebook format. Reactive by default.
• Cycle-safe — circular dependencies are detected and flagged, never silently looped
• Per-notebook control — toggle reactive mode independently for each notebook

Why Ripple

Notebooks give you the freedom to run cells in any order, but that flexibility comes with a cost: forget to re-run a downstream cell and your outputs go stale. The longer the notebook, the easier it is to lose track. Ripple takes care of that for you.

Imagine three cells:

# Cell 1
x = 1

# Cell 2
y = x * 2

# Cell 3
print(f"Result: {y}")

Change x = 1 to x = 10 and run Cell 1. Ripple re-executes Cell 2 and Cell 3 in dependency order — no manual re-running, no stale outputs.

Install

Requires JupyterLab >= 4.0.0.

pip install jupyterlab_ripple

Or try it online without installing anything.

Getting Started

After installing, Ripple is active by default. Just work as you normally would:

1. Edit and run a cell
2. Watch every downstream cell update automatically

To disable reactivity for a notebook, click the Ripple button in the toolbar.

Configuration

Ripple exposes three settings in Settings → Ripple (or schema/plugin.json):

Limitations

• Side effects not tracked — list.append(x) or obj.attr = val won't trigger downstream re-runs
• Magic commands — % and ! lines are stripped before AST analysis
• Dynamic code — exec(), eval(), and metaprogramming may confuse the analyzer

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, architecture overview, code style, testing, and linting instructions.

Uninstall

pip uninstall jupyterlab_ripple

License

MIT