Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

fix(runtime): run async notebooks from inside a running event loop (#10505)

Chinmay Rawat155ed0c411a9
diff --git a/marimo/_runtime/app/script_runner.py b/marimo/_runtime/app/script_runner.py
index 5e346f5b14..c8acb2ed73 100644
--- a/marimo/_runtime/app/script_runner.py
+++ b/marimo/_runtime/app/script_runner.py
@@ -1,7 +1,6 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-import asyncio
from typing import TYPE_CHECKING, Any
from marimo._ast.names import SETUP_CELL_NAME
@@ -11,6 +10,7 @@ from marimo._runtime import dataflow
from marimo._runtime.app.common import RunOutput
from marimo._runtime.context.types import (
get_context,
+ initialize_context,
runtime_context_installed,
teardown_context,
)
@@ -32,11 +32,13 @@ from marimo._runtime.patches import (
from marimo._runtime.runner.result import RunResult
from marimo._runtime.runner.scheduler import SequentialScheduler
from marimo._types.ids import CellId_t
+from marimo._utils.asyncio_utils import run_coroutine_blocking
if TYPE_CHECKING:
from collections.abc import Callable
from marimo._ast.app import InternalApp
+ from marimo._runtime.context.types import RuntimeContext
class AppScriptRunner:
@@ -74,7 +76,7 @@ class AppScriptRunner:
# _run_synchronous and _run_asynchronous are deliberate near-twins:
# the only difference is the await on the cell step. Keeping them
- # as separate methods (rather than wrapping with asyncio.run
+ # as separate methods (rather than driving an event loop
# unconditionally) preserves the no-event-loop guarantee for purely
# synchronous apps.
def _run_synchronous(
@@ -145,6 +147,31 @@ class AppScriptRunner:
hook()
return outputs, glbls
+ async def _run_asynchronous_in_context(
+ self,
+ context: RuntimeContext,
+ post_execute_hooks: list[Callable[[], Any]],
+ ) -> RunOutput:
+ """Run the app's cells asynchronously under `context`.
+
+ The runtime context is thread-local. If the awaiting thread has no
+ context installed, `context` is installed for the duration of the run
+ and torn down afterwards; a thread that already has one is left
+ untouched. This makes the coroutine safe to await on a thread other
+ than the one `context` was created on.
+ """
+ installed_context = False
+ if not runtime_context_installed():
+ initialize_context(context)
+ installed_context = True
+ try:
+ return await self._run_asynchronous(
+ post_execute_hooks=post_execute_hooks,
+ )
+ finally:
+ if installed_context:
+ teardown_context()
+
def _handle_run_result(
self,
cid: CellId_t,
@@ -212,8 +239,6 @@ class AppScriptRunner:
from marimo._output.formatting import FORMATTERS
if not FORMATTERS.is_empty():
- from marimo._runtime.context import get_context
-
register_formatters(
theme=get_context().marimo_config["display"]["theme"]
)
@@ -225,8 +250,9 @@ class AppScriptRunner:
post_execute_hooks.append(close_figures)
if is_async:
- outputs, defs = asyncio.run(
- self._run_asynchronous(
+ outputs, defs = run_coroutine_blocking(
+ self._run_asynchronous_in_context(
+ get_context(),
post_execute_hooks=post_execute_hooks,
)
)
diff --git a/marimo/_utils/asyncio_utils.py b/marimo/_utils/asyncio_utils.py
index 16319af7d6..e7a6127235 100644
--- a/marimo/_utils/asyncio_utils.py
+++ b/marimo/_utils/asyncio_utils.py
@@ -7,13 +7,17 @@
where the loop's default handler would otherwise swallow them).
- `cancel_and_wait`: the `task.cancel(); await task` /
`except CancelledError` dance, in one place.
+- `run_coroutine_blocking`: `asyncio.run` that also works when the
+ calling thread already has a running loop.
"""
from __future__ import annotations
import asyncio
+import concurrent.futures
import contextlib
import sys
+import threading
from typing import TYPE_CHECKING, Any, TypeVar
from marimo import _loggers
@@ -147,9 +151,61 @@ async def cancel_and_wait(task: asyncio.Task[Any]) -> None:
await task
+def run_coroutine_blocking(
+ coro: Coroutine[Any, Any, T],
+ *,
+ thread_name: str = "marimo-blocking-coroutine",
+) -> T:
+ """Run `coro` to completion and return its result, blocking the caller.
+
+ Behaves like `asyncio.run` when the calling thread has no running event
+ loop. When a loop *is* already running, `asyncio.run` raises
+ `RuntimeError`, so the coroutine is driven on a dedicated worker thread
+ with its own loop while the calling thread blocks on the result. This
+ lets synchronous APIs stay synchronous when they're called from async
+ code, instead of failing outright.
+
+ The caller's loop is blocked for the duration, so this is only
+ appropriate for APIs that are synchronous by contract.
+
+ Note that `coro` may run on a different thread than the caller. Anything
+ it needs from thread-local state (such as marimo's runtime context) has
+ to be established inside `coro` itself.
+ """
+
+ def _run() -> T:
+ # Match the selector-loop policy marimo relies on elsewhere; only
+ # done on paths that actually create a loop.
+ initialize_asyncio()
+ return asyncio.run(coro)
+
+ try:
+ asyncio.get_running_loop()
+ except RuntimeError:
+ return _run()
+
+ # A bare thread rather than a ThreadPoolExecutor: the executor's
+ # context manager shuts down with `wait=True`, so a KeyboardInterrupt
+ # while the caller is blocked would hang until the nested run finished.
+ # `Future.result()` waits on a condition variable, which the interrupt
+ # can break out of, and a daemon thread doesn't hold up interpreter
+ # exit. The Future also re-raises with the worker's traceback intact.
+ future: concurrent.futures.Future[T] = concurrent.futures.Future()
+
+ def _target() -> None:
+ try:
+ future.set_result(_run())
+ except BaseException as exc:
+ future.set_exception(exc)
+
+ threading.Thread(target=_target, name=thread_name, daemon=True).start()
+ return future.result()
+
+
__all__ = [
"cancel_and_wait",
"fire_and_forget",
"initialize_asyncio",
+ "run_coroutine_blocking",
"supervised_task",
]
diff --git a/tests/_ast/test_app.py b/tests/_ast/test_app.py
index f7f2a55d4b..e0b11dc7a3 100644
--- a/tests/_ast/test_app.py
+++ b/tests/_ast/test_app.py
@@ -631,6 +631,142 @@ class TestApp:
assert defs["x"] == 0
assert defs["y"] == 1
+ @staticmethod
+ async def test_run_async_from_running_event_loop() -> None:
+ """An async app can be run from inside a running event loop.
+
+ Regression test for #9572 / #9646: the script runner used to call
+ `asyncio.run` unconditionally, which raises when a loop is already
+ running on the calling thread.
+ """
+ app = App()
+
+ @app.cell
+ async def __() -> tuple[Any, int]:
+ import asyncio
+
+ await asyncio.sleep(0.01)
+ x = 0
+ return (
+ asyncio,
+ x,
+ )
+
+ @app.cell
+ def __(x: int) -> tuple[int]:
+ y = x + 1
+ return (y,)
+
+ _, defs = app.run()
+
+ assert defs["x"] == 0
+ assert defs["y"] == 1
+
+ @staticmethod
+ async def test_run_async_from_running_event_loop_preserves_context() -> (
+ None
+ ):
+ """The caller's thread-local runtime context survives the offload."""
+ from marimo._runtime.context.types import runtime_context_installed
+
+ app = App()
+
+ @app.cell
+ async def __() -> tuple[Any, int]:
+ import asyncio
+
+ await asyncio.sleep(0)
+ x = 1
+ return (asyncio, x)
+
+ assert not runtime_context_installed()
+ _, defs = app.run()
+ assert defs["x"] == 1
+ # The script context is ephemeral; the worker thread must not leak
+ # one back onto the calling thread.
+ assert not runtime_context_installed()
+
+ @staticmethod
+ async def test_run_async_from_running_event_loop_propagates_error() -> (
+ None
+ ):
+ """Cell errors still surface unwrapped when the run is offloaded."""
+ app = App()
+
+ @app.cell
+ async def __() -> tuple[Any]:
+ import asyncio
+
+ await asyncio.sleep(0)
+ raise ValueError("boom")
+ return (asyncio,)
+
+ with pytest.raises(ValueError, match="boom"):
+ app.run()
+
+ @staticmethod
+ async def test_embed_async_app_outside_notebook() -> None:
+ """`await app.embed()` works for an async app run as a script.
+
+ Outside a notebook `embed()` delegates to `App.run()`, so it hit the
+ same nested-event-loop failure (#9572).
+ """
+ app = App()
+
+ @app.cell
+ async def __() -> tuple[Any, int]:
+ import asyncio
+
+ await asyncio.sleep(0)
+ x = 2
+ return (asyncio, x)
+
+ result = await app.embed()
+
+ assert result.defs["x"] == 2
+
+ @staticmethod
+ async def test_run_async_app_nested_in_async_app() -> None:
+ """An async app can run another async app from one of its cells.
+
+ This is the shape reported in #9646: a notebook that runs another
+ notebook while its own event loop is live.
+ """
+ inner_app = App()
+
+ @inner_app.cell
+ async def __() -> tuple[Any, int]:
+ import asyncio
+
+ await asyncio.sleep(0)
+ inner = 21
+ return (asyncio, inner)
+
+ parent = App()
+
+ @parent.cell
+ async def __() -> tuple[Any]:
+ import asyncio
+
+ await asyncio.sleep(0)
+ return (asyncio,)
+
+ @parent.cell
+ def __() -> tuple[Any]:
+ # Overridden below; stands in for the `import notebook` cell of
+ # a real notebook.
+ child = None
+ return (child,)
+
+ @parent.cell
+ def __(child: Any) -> tuple[int]:
+ outer = child.run()[1]["inner"] * 2
+ return (outer,)
+
+ _, defs = parent.run(defs={"child": inner_app})
+
+ assert defs["outer"] == 42
+
@staticmethod
def test_run_mo_stop() -> None:
app = App()
diff --git a/tests/_utils/test_asyncio_utils.py b/tests/_utils/test_asyncio_utils.py
index 77f76a72ed..b45024ef3b 100644
--- a/tests/_utils/test_asyncio_utils.py
+++ b/tests/_utils/test_asyncio_utils.py
@@ -1,12 +1,14 @@
from __future__ import annotations
import asyncio
+import threading
import pytest
from marimo._utils.asyncio_utils import (
cancel_and_wait,
fire_and_forget,
+ run_coroutine_blocking,
supervised_task,
)
@@ -129,3 +131,59 @@ async def test_cancel_and_wait_done_task_is_noop() -> None:
task = asyncio.create_task(fast())
await task
await cancel_and_wait(task)
+
+
+def test_run_coroutine_blocking_without_running_loop() -> None:
+ async def work() -> int:
+ await asyncio.sleep(0)
+ return 42
+
+ assert run_coroutine_blocking(work()) == 42
+
+
+def test_run_coroutine_blocking_without_running_loop_stays_on_thread() -> None:
+ caller = threading.get_ident()
+
+ async def work() -> int:
+ return threading.get_ident()
+
+ # No loop is running, so there is no reason to pay for a worker thread.
+ assert run_coroutine_blocking(work()) == caller
+
+
+async def test_run_coroutine_blocking_with_running_loop() -> None:
+ async def work() -> int:
+ await asyncio.sleep(0)
+ return 42
+
+ # `asyncio.run` would raise here; the coroutine is offloaded instead.
+ assert run_coroutine_blocking(work()) == 42
+
+
+async def test_run_coroutine_blocking_with_running_loop_uses_worker() -> None:
+ caller = threading.get_ident()
+
+ async def work() -> int:
+ return threading.get_ident()
+
+ assert run_coroutine_blocking(work()) != caller
+
+
+async def test_run_coroutine_blocking_propagates_exception() -> None:
+ async def boom() -> None:
+ raise ValueError("boom")
+
+ with pytest.raises(ValueError, match="boom"):
+ run_coroutine_blocking(boom())
+
+
+async def test_run_coroutine_blocking_nests() -> None:
+ async def inner() -> int:
+ await asyncio.sleep(0)
+ return 2
+
+ async def outer() -> int:
+ # Each level has its own running loop, so each offloads again.
+ return 1 + run_coroutine_blocking(inner())
+
+ assert run_coroutine_blocking(outer()) == 3