feat: move matplotlib interactive to use marimo comm instead of over WS by mscolnick · Pull Request #8612 · marimo-team/marimo

mscolnick · 2026-03-07T17:31:31Z

Replaces the separate uvicorn server + WebSocket proxy architecture for interactive matplotlib plots with marimo's built-in MarimoComm bidirectional communication channel.

Before: mo.mpl.interactive() spun up a background uvicorn server, rendered figures in an iframe, and proxied WebSocket connections through the marimo server. This didn't work in WASM/Pyodide (no threads, no WebSockets, no separate servers) and added significant complexity.

After: Interactive matplotlib uses the same MarimoComm/MODEL_MANAGER path as anywidget, with a fake WebSocket adapter on each side. No separate server, no iframe, no proxy endpoints.

Changes

New: from_mpl_interactive.py — UIElement that bridges FigureManagerWebAgg to MarimoComm
New: MplInteractivePlugin.tsx + mpl-websocket-shim.ts — frontend plugin using MODEL_MANAGER
Simplified: _mpl.py — removed ~400 lines (server manager, starlette app, WS proxy, iframe template)
Deleted: mpl.py endpoint, test_mpl_endpoints.py, mpl proxy fixtures from middleware tests
Static assets (mpl.js, CSS) served as cached virtual files instead of inlined per-element
Figure dimensions passed from backend to prevent resize flicker on first render

What this enables

Interactive matplotlib in WASM/Pyodide
No background threads or separate server process
No WebSocket proxy or iframe isolation needed

Replaces the separate uvicorn server + WebSocket proxy architecture for interactive matplotlib plots with marimo's built-in MarimoComm bidirectional communication channel. **Before:** `mo.mpl.interactive()` spun up a background uvicorn server, rendered figures in an iframe, and proxied WebSocket connections through the marimo server. This didn't work in WASM/Pyodide (no threads, no WebSockets, no separate servers) and added significant complexity. **After:** Interactive matplotlib uses the same MarimoComm/MODEL_MANAGER path as anywidget, with a fake WebSocket adapter on each side. No separate server, no iframe, no proxy endpoints. ### Changes - **New:** `from_mpl_interactive.py` — UIElement that bridges `FigureManagerWebAgg` to `MarimoComm` - **New:** `MplInteractivePlugin.tsx` + `mpl-websocket-shim.ts` — frontend plugin using MODEL_MANAGER - **Simplified:** `_mpl.py` — removed ~400 lines (server manager, starlette app, WS proxy, iframe template) - **Deleted:** `mpl.py` endpoint, `test_mpl_endpoints.py`, mpl proxy fixtures from middleware tests - Static assets (mpl.js, CSS) served as cached virtual files instead of inlined per-element - Figure dimensions passed from backend to prevent resize flicker on first render ### What this enables - Interactive matplotlib in WASM/Pyodide - No background threads or separate server process - No WebSocket proxy or iframe isolation needed

vercel · 2026-03-07T17:31:34Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Mar 10, 2026 0:22am

Copilot

Pull request overview

This PR replaces the architecture for interactive matplotlib plots from a separate uvicorn server + WebSocket proxy + iframe approach to using marimo's built-in MarimoComm bidirectional communication channel (the same path used by anywidget). This eliminates ~700 lines of server/proxy infrastructure and enables interactive matplotlib in WASM/Pyodide environments.

Changes:

New from_mpl_interactive.py UIElement that bridges FigureManagerWebAgg to MarimoComm, and new frontend MplInteractivePlugin.tsx + mpl-websocket-shim.ts that receives comm messages and drives mpl.js
Removed the entire mpl proxy endpoint (mpl.py), starlette server, WebSocket proxy, and all related tests/fixtures
Static assets (CSS, JS, toolbar images) served as cached virtual files instead of via the mpl server

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`marimo/_plugins/ui/_impl/from_mpl_interactive.py`	New UIElement bridging FigureManagerWebAgg to MarimoComm
`marimo/_plugins/stateless/mpl/_mpl.py`	Removed ~400 lines of server/proxy code, kept shared utilities
`marimo/_server/api/endpoints/mpl.py`	Deleted - HTTP/WS proxy endpoints no longer needed
`marimo/_server/api/router.py`	Removed mpl_router from route registration
`frontend/src/plugins/impl/mpl-interactive/MplInteractivePlugin.tsx`	New React plugin component using MODEL_MANAGER
`frontend/src/plugins/impl/mpl-interactive/mpl-websocket-shim.ts`	Fake WebSocket adapter translating comm messages
`frontend/src/plugins/impl/mpl-interactive/__tests__/mpl-websocket-shim.test.ts`	Tests for the websocket shim
`frontend/src/plugins/plugins.ts`	Registered the new MplInteractivePlugin
`frontend/vite.config.mts`	Suppressed rollup externalization warnings
`tests/_plugins/ui/_impl/test_from_mpl_interactive.py`	New comprehensive tests for the backend UIElement
`tests/_plugins/stateless/test_mpl.py`	Updated tests for simplified mpl module
`tests/_server/api/test_middleware.py`	Removed mpl proxy test fixtures and tests
`tests/_server/api/endpoints/test_mpl_endpoints.py`	Deleted - mpl endpoint tests no longer needed
`marimo/_smoke_tests/iplot.py`	Updated smoke test for new architecture

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-07T17:38:26Z

frontend/src/plugins/impl/mpl-interactive/MplInteractivePlugin.tsx

+    const script = document.createElement("script");
+    script.src = jsUrl;
+    script.onload = () => resolve();
+    script.onerror = () => reject(new Error("Failed to load mpl.js"));


If mpl.js fails to load (e.g., network error), mplJsLoading holds the rejected promise forever and all subsequent calls to ensureMplJs will return the same rejected promise without retrying. Consider resetting mplJsLoading = null in the onerror handler so that a subsequent figure instantiation can retry the load.

Suggested change

script.onerror = () => reject(new Error("Failed to load mpl.js"));

script.onerror = () => {

mplJsLoading = null;

reject(new Error("Failed to load mpl.js"));

};

Copilot · 2026-03-07T17:38:27Z

frontend/src/plugins/impl/mpl-interactive/MplInteractivePlugin.tsx

+
+    setupFigure(container).then((cleanupFn) => {
+      cleanup = cleanupFn;
+    });
+
+    return () => {


The setupFigure promise is not guarded against rejection. If ensureMplJs or MODEL_MANAGER.get throws, the error is silently swallowed (unhandled promise rejection). Additionally, there's a race condition: if the effect cleanup runs before setupFigure resolves, cleanup will be undefined and the model's msg:custom listener will never be removed, causing a leak.

Consider adding a .catch() for error handling and using a cancelled flag (set in the cleanup) to prevent the .then() callback from running after the component unmounts or the effect re-fires.

Suggested change

setupFigure(container).then((cleanupFn) => {

cleanup = cleanupFn;

});

return () => {

let cancelled = false;

setupFigure(container)

.then((cleanupFn) => {

if (cancelled) {

return;

}

cleanup = cleanupFn;

})

.catch((error) => {

if (cancelled) {

return;

}

Logger.error("Failed to set up MPL interactive figure", error);

});

return () => {

cancelled = true;

Copilot · 2026-03-07T17:38:27Z

marimo/_plugins/ui/_impl/from_mpl_interactive.py

+def _get_mpl_css() -> str:
+    """Collect all matplotlib WebAgg CSS files and our custom CSS."""
+    from matplotlib.backends.backend_webagg_core import (
+        FigureManagerWebAgg,
+    )
+
+    static_path = Path(
+        FigureManagerWebAgg.get_static_file_path()  # type: ignore[no-untyped-call]
+    )
+    parts: list[str] = []
+    for css_file in sorted(static_path.glob("css/*.css")):
+        parts.append(css_file.read_text())
+    # Our own overrides
+    parts.append(css_content)
+    return "\n".join(parts)


The custom CSS contains rules targeting body (background-color: transparent; width: 100%) and #figure (line 126). Previously these were scoped within an iframe, but now the CSS is injected directly into the page as a <link> tag. The body rules will leak and affect the entire page.

Additionally, _get_mpl_css() also collects matplotlib's own CSS files (like page.css, boilerplate.css) which may contain similarly broad selectors. These should either be scoped to a container class/element, or be loaded inside a Shadow DOM to prevent CSS leaking.

- Reset mplJsLoading on script load failure so retries work - Guard setupFigure promise with cancelled flag and .catch() - Add expect() assertion to receiveJson no-op test - Skip boilerplate.css and page.css that have global selectors (body, html, div) which leak into host page now that we're not in an iframe - Remove body/figure CSS rules from css_content (iframe-only) - Fix CSS pixel calculation to use canvas.get_width_height() for SubFigure compat

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dmadisetti

SO much better than spawning up a server. This clears a ton of smells.

I want to maybe test this out a tiny bit- the only comments I have in the meantime are:

link to matplotlib docs/source somewhere. I needed these for review, and it'll be good to have in case of internal api changes: https://github.com/matplotlib/matplotlib/blob/9d83ca60096f313dfc9f144288501af18c770a4e/lib/matplotlib/backends/backend_webagg_core.py#L459
The CSS scoping maybe looks a little brittle

but that's it

mscolnick · 2026-03-11T01:03:03Z

@dmadisetti, i moved the CSS scope to a variable and simplified it greatly. also added the comment in code. going to merge but feel free to check out if you have more comments

Copilot AI review requested due to automatic review settings March 7, 2026 17:31

mscolnick requested review from Light2Dark and manzt as code owners March 7, 2026 17:31

Copilot started reviewing on behalf of mscolnick March 7, 2026 17:31 View session

vercel bot deployed to Preview March 7, 2026 17:32 View deployment

Copilot AI reviewed Mar 7, 2026

View reviewed changes

mscolnick added the enhancement New feature or request label Mar 7, 2026

vercel bot deployed to Preview March 7, 2026 18:09 View deployment

mscolnick requested a review from Copilot March 7, 2026 18:19

Copilot started reviewing on behalf of mscolnick March 7, 2026 18:20 View session

fix: apply ESLint and biome auto-fixes for MplInteractivePlugin

4d858fe

vercel bot deployed to Preview March 7, 2026 18:22 View deployment

fix: use querySelector generic instead of cast for HTMLElement

a305a71

vercel bot deployed to Preview March 7, 2026 18:25 View deployment

Copilot AI reviewed Mar 7, 2026

View reviewed changes

mscolnick mentioned this pull request Mar 7, 2026

fix: mo.mpl.interactive renders blank in marimo run mode (#8452) #8599

Closed

fix: address review comments on mpl interactive

5759295

vercel bot deployed to Preview March 9, 2026 17:16 View deployment

dmadisetti reviewed Mar 9, 2026

View reviewed changes

docs

073f28d

vercel bot deployed to Preview March 9, 2026 19:47 View deployment

simpler scope css

5704ec2

vercel bot deployed to Preview March 10, 2026 00:16 View deployment

improvements

8ae3acd

vercel bot deployed to Preview March 10, 2026 00:22 View deployment

mscolnick merged commit 45e12f3 into main Mar 11, 2026
33 of 43 checks passed

mscolnick deleted the ms/beter-mpl branch March 11, 2026 01:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: move matplotlib interactive to use marimo comm instead of over WS#8612

feat: move matplotlib interactive to use marimo comm instead of over WS#8612
mscolnick merged 8 commits intomainfrom
ms/beter-mpl

mscolnick commented Mar 7, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI Mar 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

dmadisetti left a comment

Uh oh!

mscolnick commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

mscolnick commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

What this enables

Uh oh!

vercel bot commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

dmadisetti left a comment

Choose a reason for hiding this comment

Uh oh!

mscolnick commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mscolnick commented Mar 7, 2026 •

edited

Loading

vercel bot commented Mar 7, 2026 •

edited

Loading