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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs: describe cache_cells and its use for WASM exports (#10455)
Dylan Madisetti9051a5d5463b
diff --git a/docs/api/caching.md b/docs/api/caching.mdindex e05e68c1a6..2501033eae 100644--- a/docs/api/caching.md+++ b/docs/api/caching.md@@ -105,6 +105,46 @@ code will be skipped and your variables will be loaded into memory. The cachekey for the context manager is computed in the same way as it is computed fordecorated functions.+## Automatic cell caching++`mo.cache` and `mo.persistent_cache` are opt-in per function or code block. marimo+also has a notebook-wide mechanism that automatically attempts to cache+**every** executed cell, not just the ones you have explicitly decorated.++Enable it with:++```toml title="pyproject.toml"+[tool.marimo.runtime]+cache_cells = true+```++!!! tip "Configuring for your project"+ Set the above snippet in your notebook's `pyproject.toml` as shown above,+ or directly in your notebooks' PEP 723 metadata.++With `cache_cells` enabled, marimo attempts to save and restore every cell's+state on notebook restart. On a cache hit, marimo skips re-running the cell and+hydrates its variables from a stored stub instead. If a stub cannot be hydrated+(for example, its value is not hashable or serializable), marimo invalidates+the cache for that cell and its producing ancestors, then re-runs them live.+You do not need to clear anything manually.++!!! warning "Experimental"+ UI elements defined by a cached cell are not currently restored from+ cache on a cache hit, which forces a live re-run of that cell. Smarter+ caching (skipping cells where caching itself is slow) and+ surfacing more information about cache hits and misses in the UI are+ planned but not yet implemented.++Cached cell execution is also what powers [cached WASM+exports](../guides/exporting/webassembly_html.md#exporting-with-cached-execution),+which let you publish notebooks whose expensive or browser-incompatible cells+were computed elsewhere beforehand.++!!! tip "Further reading"+ For more on the design of marimo's caching, see our SciPy paper+ (currently under peer review):+ [github.com/scipy-conference/scipy_proceedings/pull/1262](https://github.com/scipy-conference/scipy_proceedings/pull/1262)## Cache keydiff --git a/docs/guides/configuration/runtime_configuration.md b/docs/guides/configuration/runtime_configuration.mdindex 02803f2356..4881920e9a 100644--- a/docs/guides/configuration/runtime_configuration.md+++ b/docs/guides/configuration/runtime_configuration.md@@ -35,15 +35,34 @@ when working on notebooks with expensive cells.!!! tip "Tip: speed up expensive notebooks with marimo's smart caching"In addition to runtime configuration, marimo also provides [opt-in caching](../../api/caching.md)- to help you work with expensive or side-effectful notebooks. marimo's+ to help you work with expensive or side-effectful notebooks. marimocan cache expensive functions in memory and expensive blocks of code to disk,letting you skip entire sections of your code and automatically loading- variables in memory on notebook startup. Read our [caching- guide](../../api/caching.md) to learn more.+ variables in memory on notebook startup. marimo can also automatically+ cache every executed cell notebook-wide. See [`cache_cells`](#cache-cells)+ below. Read our [caching guide](../../api/caching.md) to learn more._When sharing a notebook as an app with `marimo run`, this setting hasno effect._+## Cache cells { #cache-cells }++By default, marimo only caches the functions or code blocks you explicitly+decorate with [`mo.cache`][marimo.cache] or+[`mo.persistent_cache`][marimo.persistent_cache]. You can instead have marimo+attempt to cache every executed cell in the notebook by setting `cache_cells`+in the runtime configuration:++```toml title="pyproject.toml"+[tool.marimo.runtime]+cache_cells = true+```++Set it in `pyproject.toml` as shown above, or in the notebook's PEP 723+metadata. See [Automatic cell+caching](../../api/caching.md#automatic-cell-caching) for how this behaves and+its current limitations.+## On module changeWhen module autoreloading is enabled, marimo automatically runs cells when youdiff --git a/docs/guides/exporting/webassembly_html.md b/docs/guides/exporting/webassembly_html.mdindex a340f79e0a..27ed688321 100644--- a/docs/guides/exporting/webassembly_html.md+++ b/docs/guides/exporting/webassembly_html.md@@ -22,6 +22,7 @@ Options:- `--show-code/--no-show-code`: Whether to initially show or hide the code in the notebook- `--watch/--no-watch`: Watch the notebook for changes and automatically export- `--include-cloudflare`: Write configuration files necessary for deploying to Cloudflare+- `--execute/--no-execute`: Run the notebook before exporting and embed its outputs as a preview. Where possible, this uses an isolated environment pinned to WASM-compatible packagesNote that WebAssembly notebooks have [limitations](../wasm.md#limitations); in particular,[many but not all packages work](../wasm.md#packages). If your notebook runs both@@ -29,6 +30,13 @@ locally and in the browser, use [PEP 508 environmentmarkers](../wasm.md#platform-specific-dependencies-pep-508) in script metadata toexclude native-only dependencies from WASM installs.+Run `marimo check notebook.py --select MW` before exporting to catch WASM+incompatibilities early:++- [MW001](../lint_rules/rules/incompatible_import.md): an incompatible import+- [MW002](../lint_rules/rules/unsafe_system_call.md): an unsafe system call+- [MW003](../lint_rules/rules/incompatible_package.md): a dependency without a WASM-compatible wheel+!!! note "Note"The exported file must be served over HTTP to function correctly - it@@ -58,6 +66,171 @@ exclude native-only dependencies from WASM installs.npx wrangler deploy```+## Exporting with cached execution { #exporting-with-cached-execution }++With caching, you can publish WebAssembly notebooks whose cells are expensive+or cannot run in the browser (a small `torch` training run, for example). If your+notebook has [automatic cell+caching](../../api/caching.md#automatic-cell-caching) enabled, `--execute` runs+the notebook once and bundles the resulting cell cache into the export. When the+exported notebook loads, each cached cell hydrates from that bundle instead of+recomputing in WebAssembly. The rest of the notebook stays fully live and+interactive.++Bundling a cache needs both the runtime setting and the `--execute` flag:++```toml title="pyproject.toml"+[tool.marimo.runtime]+cache_cells = true+```++```bash+marimo export html-wasm notebook.py -o output_dir --execute+```++marimo copies the cached entries into a `public/cache/` directory alongside the+export. At load time, the browser runtime fetches them over HTTP instead of+recomputing the corresponding cells.++### Cached values from packages WebAssembly cannot install { #native-only-objects }++A cached cell can define a top-level value from a package that WebAssembly+cannot install, like a `torch.nn.Module`. You do not need to keep such values+out of the cache. When the exported notebook cannot correctly restore+variables from cache, marimo binds the variable to a stub instead of raising+an error. The notebook will load normally and behave normally as the+evaluation of the stubbed variable is deferred until an attempt to use it.++When an incompatible variable load is triggered, marimo will attempt to+recompute its definition from the notebook, which in turn may fail if the+behavior is not compatible with the WebAssembly environment.++For instance, if the browser does not have a package a new cell needs, the rerun fails:++```python+# /// script+# dependencies = [+# "marimo",+# "torch; sys_platform != 'emscripten'", # native-only; excluded from WASM+# ]+#+# [tool.marimo.runtime]+# cache_cells = true+# ///++# --- Cell 1 ---++import torch # load deferred; torch is not available in the browser+import numpy as np++# --- Cell 2 --- # Cell 2 is cached and skipped+model = torch.nn.Linear(4, 2)+# ... train the model ...++# --- Cell 3 --- # Cell 3 is cached and skipped+x = np.array(model(torch.rand(1, 4)))+x # Output is initially visible!++# --- Cell 4 --- # If this is a new cell it'll still work! `x` is loaded from cache.+x + x # numpy values can be used in the browser, so this works fine++# --- Cell 5 --- # If this is a new cell, this will fail+np.array(model(torch.rand(1, 4)))+```++In the exported notebook, `model` hydrates as a stub. Displaying outputs or+referencing the variable in other cached cells still works. Calling `model(...)`+in the new Cell 5 reruns this cell live. That rerun needs `torch`, which is+unavailable in the browser, so it fails there.++To run inference on such a model in the browser, cache a portable form of it+instead of calling the stub. [`moutils.onnx.OnnxRuntime`](https://github.com/marimo-team/moutils#onnx-runtime-adapter)+does this for PyTorch and JAX models: it exports the model to ONNX, and the+runtime it returns is itself cacheable. In the browser, that runtime runs+inference with `onnxruntime-web` instead of the original framework.++!!! note "This is a point-in-time snapshot"++ Cache bundling covers only the cells whose cache is valid at export time.+ Editing a cell, or changing an input it depends on, invalidates that+ cell's cache. Then the browser must run the cell's real code instead of+ hydrating it from the bundle. If that code needs a package WebAssembly+ cannot install (like `torch`), the cell reports an error. After such a+ change, re-run and re-export the notebook.++### Caching precomputed values { #precomputed-values }++An alternative to caching for runtime evaluation is precomputing every+possible output of a cell and bundling them into the export. This is useful for+notebooks that have a small, known set of states, such as those with dropdowns+or sliders that index into a fixed list of options. By precomputing every+reachable output ahead of time, you can avoid waiting for the cache to warm up+during use.++The pattern has four parts:++1. Expose UI elements as indices into fixed option lists of plain, hashable+ values (strings, numbers) — not the objects or callables the indices+ select. UI-defining cells always rerun live on load, even on a cache hit,+ so keep them free of anything that touches an unavailable package.+2. Pull the expensive computation into a plain function keyed on those indices,+ decorated with `@mo.persistent_cache(method="lazy")`. Use `method="lazy"`:+ `method="pickle"` does not bundle well for the WASM export.+3. Add a cell that calls that function for every combination of indices,+ guarded to run only outside the browser, for example with+ `sys.platform != "emscripten"`.+4. Return WASM-native values (numbers, `numpy` arrays, strings) from the+ cached function, so cells that use the result work directly in the+ browser.++```python+# /// script+# dependencies = [+# "marimo",+# "torch; sys_platform != 'emscripten'", # native-only; excluded from WASM+# ]+#+# [tool.marimo.runtime]+# cache_cells = true+# ///++# --- Cell 1 --- # setup; not UI-defining, so a cache hit can skip it entirely+import sys+import torch+import marimo as mo++FN_LABELS = ["x^2", "sin(x)"]++# --- Cell 2 --- # UI-defining cells always rerun live on load, so keep them+# to plain, hashable literals like FN_LABELS above+fn = mo.ui.dropdown(+ options={label: i for i, label in enumerate(FN_LABELS)}, value="x^2"+)+fn++# --- Cell 3 --- # the expensive part, keyed on the dropdown's index[email protected]_cache(method="lazy")+def compute(fn_idx):+ x = torch.linspace(-1, 1, 100)+ y = x**2 if fn_idx == 0 else torch.sin(x)+ return {"label": FN_LABELS[fn_idx], "x": x.numpy(), "y": y.numpy()}++# --- Cell 4 ---+result = compute(fn.value)+result++# --- Cell 5 --- # warm the cache for every dropdown option before exporting+if sys.platform != "emscripten":+ for _fn_idx in range(len(FN_LABELS)):+ compute(_fn_idx)+```++Export with `marimo export html-wasm notebook.py -o output_dir --execute`.+The precompute cell runs during that server-side pass and populates one+cache entry per dropdown option. All of them get bundled into+`public/cache/`. In the browser, every dropdown selection is already+cached, so switching between options never triggers a live rerun.+## Including local modules and wheels`marimo export html-wasm` includes Python modules imported by your notebook