Compatibility and support
marimo-studio 0.2 is the current compatibility line. The notebook-to-view workflow, projection elements, and last-successful build behavior are supported product contracts. Before 1.0, CLI, Python, provider, and saved configuration contracts may change between minor releases.
Add Studio to the notebook or project dependencies:
dependencies = ["marimo-studio"]Use marimo-studio[deno] to enable every bundled starter. The deno extra supplies the Deno toolchain that the React, Reveal.js, Svelte, and Notebook Kit starters build with.
Upgrade from 0.0.6
Version 0.1.1 introduces explicit view manifests and a notebook-bound authoring API. Update saved view projects and automation before opening them with 0.1.1.
Add this view.toml to each existing 0.0.6 view directory:
schema = 1
provider = "marimo-studio/vanilla"Keep the existing index.html and any CSS or JavaScript files it references. Then run marimo-studio status --target analysis.py. Studio discovers the view, assigns its owner record, and reports its Source documents. Commit view.toml and the generated .owners/ records with the view project.
Update command and Python callers with these replacements:
| 0.0.6 contract | 0.1.1 replacement |
|---|---|
marimo-studio inspect TARGET --display | marimo-studio notebook inspect --target TARGET --output-expressions |
marimo-studio bind TARGET --cell 12 --as summary | marimo-studio notebook bind summary --target TARGET --cell 12 |
marimo-studio view add TARGET --name report | marimo-studio view create report --target TARGET |
marimo-studio view list TARGET | marimo-studio status --target TARGET |
marimo-studio view remove TARGET --name report | marimo-studio view remove report --target TARGET |
marimo-studio check TARGET --view report --runtime | marimo-studio validate report --target TARGET --level runtime |
marimo-studio analyze TARGET --view report --server URL | marimo-studio view preview report --target TARGET --runtime server --server URL |
marimo-studio export TARGET --view report --output dist/report | marimo-studio view export report --target TARGET --output dist/report --runtime wasm |
--format json --diagnostics jsonl | --json |
Functions in marimo_studio.agents | marimo_studio.agent.current_workspace() and its Workspace or View methods |
Saved-workspace helpers in marimo_studio.workspace, checks, and export | marimo_studio.authoring.open_workspace() and its Workspace or View methods |
CellConfigSpec, CellRef, CellSpec, and SourceSpan from marimo_studio | Import these provider-facing records from marimo_studio.view_providers |
Notebook-local [tool.marimo-studio] configuration and project pyproject.toml configuration are mutually exclusive for one notebook. Keep one configuration source before running the upgraded commands.
After updating the workspace, run:
marimo-studio status --target analysis.py
marimo-studio validate --target analysis.py --level runtimeRuntime validation executes the complete notebook with the current user's filesystem, environment, and network authority. Run it for trusted notebooks.
Supported environment
| Component | 0.2.0 contract |
|---|---|
| Python | 3.10 through 3.14 |
| marimo | 0.25.1 |
| Deno | 2.9.5 from the deno extra for React, Reveal.js, Svelte, and Notebook Kit authoring |
| uv | Required when the CLI must prepare or re-enter a notebook or provider environment |
| Browser acceptance | Current Chromium on Linux and Windows |
Windows builds and exports require Win32 long paths, which lets Python create staging files beyond the default 260-character path limit. Enable LongPathsEnabled=1 with administrator privileges before starting Studio. Restart existing Studio and terminal processes after changing the setting.
The Python runtime can use the packages, files, databases, and credentials available to its Python environment. The Browser runtime requires Pyodide-compatible packages and data sources the visitor can reach. Run or export a view defines those runtime and delivery boundaries.
Workspace storage
Studio keeps the notebook, its configuration, and every view project in the notebook workspace. Each change publishes its result in one atomic step that never replaces an existing name: an exclusive rename, or a hard link or empty placeholder where the filesystem has no exclusive rename. Each change also compares stable file identities, so the workspace must live on storage that provides both:
| Platform | Supported workspace storage |
|---|---|
| Linux and macOS | Local ext4, XFS, Btrfs, or APFS disks, NFSv3 and NFSv4 shares, and gVisor sandbox mounts |
| Windows | NTFS, ReFS, SMB shares, and OneDrive or SharePoint-synced folders |
| WSL 2 | The Linux disk and NTFS drives mounted under /mnt |
Windows cloud-sync folders use data reparse points for online files. Studio opens those entries through the cloud filter, while symlinks and junctions remain outside the workspace contract.
Object-storage mounts such as s3fs and rclone rewrite file timestamps when Studio reads a file and can drop file content when a directory is renamed. exFAT and FAT32 drives renumber a file when it is renamed. Studio treats those changes as concurrent edits and stops the operation. Copy the workspace to supported storage before opening it, or let the hosting platform copy it into the session and save it back afterwards.
Runtime and delivery matrix
| Delivery | Python server | Browser wasm | Prepared zero-python |
|---|---|---|---|
| Studio Preview | Supported | Supported | Supported in edit mode |
| Live run-mode server | Supported | Supported | Not applicable |
| Static export | Not applicable | Supported | Default |
Static exports are HTTP directories. A Prepared export contains the production artifact, runtime configuration, notebook public files, and prepared projection results. A Browser export also contains saved notebook source and runs it through Pyodide. Imported packages, remote data, fonts, maps, and other browser resources retain their own network and cross-origin requirements.
Deployment boundary
create_asgi_app() and marimo_studio.asgi:app return a run-mode marimo ASGI application with Studio middleware and owned lifespan cleanup. ASGI is the standard interface between asynchronous Python web applications and servers. The hosting stack owns TLS connection encryption, proxy headers, process supervision, resource limits, and network exposure. Forward the application lifespan so Studio can close notebook sessions and background tasks during shutdown.
marimo authentication supplies read and edit scopes to Studio routes. Source mutations also require the marimo server token. Run-mode presentations use read access. Keep authentication enabled when a deployment can execute Python code or reach private files, services, or credentials.
Provider-authored pages run inside a sandboxed iframe, an embedded browser document, with an opaque origin. The sandbox permits scripts, forms, downloads, modals, pointer lock, and popups. It withholds same-origin access and top-level navigation. Studio validates navigation, query, replay, and readiness messages at the parent boundary.
Set MARIMO_STUDIO_TRUSTED_SERVER_RUNTIME=1 for a trusted single-tenant deployment that needs Server runtime documents to share the authenticated host origin. A marimohub session with proxy exposure enables it when the variable is unset, because the hub already serves notebook output on its own origin. The policy covers view documents, workspace previews, and the ASGI embedding path. Browser and Prepared runtimes keep opaque-origin isolation.
Third-party view providers
Studio 0.3 requires provider API version 1. Set ProviderInfo.api_version=PROVIDER_API_VERSION and declare marimo-studio as a dependency. Test the provider against each Studio minor release it supports.
The View provider API defines process execution, permissions, cancellation, build inputs, output validation, and conformance limits. Provider packages and their child commands run with the current user's filesystem, environment, and network authority.
Support and security
Security fixes target the latest published release and the main branch. Use the latest Studio release when reporting a bug.
- Open public bug reports and support requests in GitHub Issues.
- Follow the troubleshooting guide to collect redacted diagnostic output.
- Report suspected vulnerabilities through the private path in the security policy.