Troubleshooting marimo Collaboration and Deployment Issues

When a marimo notebook behaves unexpectedly, first check its variable dependencies and run marimo check my_notebook.py. For sharing or deployment problems, verify the project environment and local files, then check the serving route—especially proxy, symlink, authentication, and sync settings. This guide covers those failure points and helps you choose between a marimo server, Kubernetes, and a static WebAssembly export.

Fix cells that do not run, rerun unexpectedly, or show stale results

marimo determines how cells depend on one another by tracking variables defined and referenced across cells. It does not track mutations to an object. If one cell changes a shared object in place, a cell that depends on it may not rerun as expected. Prefer creating a new object with the changed value, or keep the related mutation and its use in the same cell. The official troubleshooting guide describes the dependency model and diagnostics.

#	Preview	Product	Price
1		WavePad Audio Editing Software - Professional Audio and Music Editor for Anyone [Download]	$69.99	Buy on Amazon

Inspect the dependency graph

Use the minimap, dependency graph, or variables panel to see which cells are connected and where variables are defined and used. A cell that reruns too often may depend on an accidental global variable that should instead be local or passed as a function argument. A leading underscore can mark a value that is not intended for use by other cells.

If execution order is unclear, make the dependency explicit by referencing a value from the earlier cell. If you repeatedly need artificial ordering, consider refactoring the related logic rather than relying on visual cell order.

#1 Best Overall

WavePad Audio Editing Software - Professional Audio and Music Editor for Anyone [Download]

• Full-featured professional audio and music editor that lets you record and edit music, voice and other audio recordings
• Add effects like echo, amplification, noise reduction, normalize, equalizer, envelope, reverb, echo, reverse and more
• Supports all popular audio formats including, wav, mp3, vox, gsm, wma, real audio, au, aif, flac, ogg and more
• Sound editing functions include cut, copy, paste, delete, insert, silence, auto-trim and more
• Integrated VST plugin support gives professionals access to thousands of additional tools and effects

$69.99

Buy on Amazon

Run the notebook checker

Run marimo check my_notebook.py to check for issues including multiple definitions of a variable across cells, circular dependencies, and unparsable code. For runtime problems, inspect values and definitions in the variables panel, use temporary print output or mo.md(), and disable cells to isolate a failure. Lazy runtime configuration can help identify stale cells without automatically running them.

Keep UI state from resetting

If a UI value resets, check whether the cell that defines the UI element reruns: rerunning that cell reinitializes the value. Separating the UI definition from cells that rerun can help. Use mo.state when a value needs to persist across runs.

Resolve imports that work in one context but fail in another

When you start a notebook with marimo edit path/to/notebook.py or marimo run path/to/notebook.py, marimo sets sys.path to behave like python path/to/notebook.py. In particular, sys.path[0] is the notebook’s directory. If a project import fails, check whether the package is installed and whether the import path is configured relative to that directory. The troubleshooting guide points to pyproject.toml runtime configuration for adding sys.path entries.

Fix 404s for browser assets

When browser requests for marimo assets return 404, check whether the files are reached through symlinks and whether the notebook is running behind a proxy. For Bazel setups or uv symlink link mode, inspect marimo.toml and consider the documented [server] follow_symlink = true setting.

For a reverse proxy, pass its public host and port when starting marimo, for example marimo edit --proxy example.com:8080; the guide also shows the flag for marimo run. If the proxy argument omits a port, marimo defaults to port 80. For continued debugging, inspect logs under $XDG_CACHE_HOME/marimo/logs/; the guide lists github-copilot-lsp.log and pylsp.log.

Make a notebook reproducible for collaborators

A notebook file alone may not contain the project’s dependencies, data, or local source files. Choose the environment approach that fits the project and share the matching dependency records and files.

Shared project environment

For notebooks that use packages shared with the rest of a project, maintain requirements in the project environment, commonly pyproject.toml. A project-aware package manager can update both requirements and lockfiles. Installing a package with pip alone does not automatically update those project files, so collaborators may otherwise install a different environment.

Per-notebook sandbox

Sandbox mode isolates package requirements per notebook and records them in inline metadata. A lockfile is a separate step: share it along with any required data or local source files, which are not included merely by sharing the notebook. Sandbox mode isolates packages, not file or network access, so only run code you trust. See the marimo dependency-management guide for details.

Agent pairing is not the same as shared human editing

marimo pair lets a supported agent CLI inspect variables, run cells, and edit a running notebook; the documentation also describes connecting an agent to a notebook in a molab sandbox. This establishes an agent-assisted workflow, not that arbitrary multiple human editors can edit one notebook simultaneously without conflicts. See marimo’s agent-pairing documentation.

Choose a deployment route that matches how the notebook must run

The main decision is where Python executes and what users need to do: a marimo server or Kubernetes deployment runs the notebook as an app on a server, while a WebAssembly export runs in the browser. Also consider whether users need editing or read-only access, whether edits must sync to source files, and how authentication and resources will be managed. The official docs describe these options but do not prescribe one route for every workload.

Run a marimo app or gallery

marimo run notebook.py lays out a notebook as an app and starts a web server. The app guide also documents running multiple notebooks or a directory as a gallery. If a constructed layout is part of the app, commit and deploy the layouts directory: marimo stores layout metadata there. See the app deployment guide.

Deploy on Kubernetes

The marimo Kubernetes guide lists Kubernetes v1.25 or later, configured kubectl access, Python 3.9 or later with pip or uv, and cluster-admin permission for the initial operator installation as prerequisites. It recommends kubectl-marimo as a quick path from local files. The plugin workflow uploads the notebook, creates persistent storage, starts the server, and forwards a local port. Stopping kubectl marimo edit with Ctrl+C syncs changes back to the local file and tears down the pod.

For read-only app service, the guide shows kubectl marimo run notebook.py. Token authentication is the default; the guide documents auth: "none" to disable it. Treat that as a security decision: do not expose an unauthenticated service on a reachable network without assessing the risk.

Be careful how you delete a deployment. kubectl marimo delete notebook.py syncs changes before deletion, but direct kubectl delete marimo ... does not. If cluster edits must be retained locally, sync explicitly or use the plugin deletion command. The guide also covers direct MarimoNotebook manifests, persistent storage, resource limits, sidecars, port forwarding, and cloud storage. See the Kubernetes deployment guide.

Publish a WebAssembly export

For Cloudflare, the documented command is marimo export html-wasm notebook.py -o output_dir --mode run --include-cloudflare. It creates an index.js Worker script and wrangler.jsonc configuration. Preview locally with npx wrangler dev and deploy with npx wrangler deploy. The guide also describes publishing the export to Cloudflare Pages through Git or manual asset upload. See Cloudflare’s marimo notebook deployment guide.

For self-hosting, serve the exported HTML and its adjacent assets directory over HTTP. The server may need to return the correct application/wasm content type. Offline export with --offline bundles the Python runtime and packages, but not external data, APIs, or JavaScript assets fetched by notebook code or widgets; those require local alternatives. The documented offline workflow requires Playwright and its Chromium browser, and export needs internet access to resolve browser-compatible dependencies. See the WebAssembly export guide.

Quick Recap

Bestseller No. 1

WavePad Audio Editing Software - Professional Audio and Music Editor for Anyone [Download]

$69.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.