marimo

Every experienced Python user has met the same failure. A notebook works perfectly, you restart the kernel and run all, and it collapses — because it only ever worked thanks to a cell you edited, ran, and then changed, or one you deleted an hour ago whose variables are still sitting in memory.

The second failure is quieter and arguably worse. You open a pull request containing a notebook and see thousands of lines of JSON with base64-encoded image output. Nobody reviews that. Notebooks became the one part of a data codebase that escapes code review entirely.

marimo's argument is that both problems come from the same root: a notebook that stores its own output and lets you run cells in any order is not a program, it is a transcript. Its answer is to make the notebook a program — a real Python file, with an execution order derived from the code rather than from your clicking. This review covers what that buys, what it costs, and where Jupyter is still the right answer.

Reactive, Not Sequential

• Change a cell and every dependent cell re-runs, worked out by static analysis of what each cell reads and writes — no more running cells in a private order you have to remember.
• Notebooks are plain .py files, so they diff, review and merge in git like any other source code.
• Delete a cell and its variables go with it, which is the direct fix for hidden state — the defect that makes a notebook run on your machine and nowhere else.
• One file, three uses: edit it as a notebook, run it as a script, serve it as an interactive web app.
• Open source and installed with pip, with SQL cells, WASM export to static HTML, and a hosted option in molab.

Notebook Concepts That Matter Here

Four terms that explain why marimo is structured the way it is.

Hidden state

Variables alive in the kernel that no longer correspond to any cell in the file — from a cell you edited or deleted. The reason a notebook runs for you and fails for everyone else.

Reactive execution

Running cells in an order derived from the code's dependency graph rather than from the order you clicked. Change a cell and everything downstream updates.

Dependency graph

The map of which cells read which variables, built by static analysis of the code. It is what makes the execution order deterministic.

WASM export

Compiling the notebook to run entirely in a browser via WebAssembly, producing a static HTML file with no server. Removes environment setup for anyone you share it with.

Stored As Python, Which Fixes Git

A marimo notebook is a .py file. Not Python embedded in JSON, not a format that converts to Python on export — an actual Python module you can open in any editor.

The consequences run further than tidiness. Diffs become readable, so a change to a notebook can be reviewed like any other code change. Merge conflicts become resolvable rather than a reason to pick one version and discard the other. Notebooks can be imported as modules, so a function you wrote in exploration can be used elsewhere without copying it out.

It also means your linter, your formatter, your type checker and your CI all work on notebooks without a conversion step, and an assistant such as GitHub Copilot reads them as ordinary source. That sounds mundane and it removes an entire category of tooling gap that data teams have lived with for a decade.

The design decision underneath is that output does not belong in the file. A Jupyter notebook stores its results, which is why the file grows, why diffs are unreadable, and why a repository accumulates megabytes of stale charts. marimo stores the program and regenerates the output — which is only safe because reactive execution guarantees the output matches the code.

A notebook that stores its own output is a transcript. A notebook stored as a program is code you can review.

The Constraint Nobody Mentions Up Front

Reactive execution imposes a rule that catches every newcomer: a variable can be defined in only one cell.

In Jupyter, redefining df cell after cell as you clean data is the normal working style. marimo forbids it, because if two cells both define df the dependency graph has no single answer for what df means.

The adjustment is real and takes a few days. In practice it pushes you toward naming intermediate results — raw, cleaned, filtered — or toward wrapping steps in functions. Both are better practice, and both feel like friction while you are learning them.

This is the honest cost of the model. The benefit is that when you hand the notebook to someone else it runs, and that is not a small thing to trade a naming habit for.

SQL Cells Are More Than A Convenience

marimo has a built-in SQL engine, and it treats SQL as a first-class cell type rather than as a string passed to a library.

Queries can run against dataframes as well as databases and warehouses, with support spanning Polars, pandas, PyArrow, DuckDB, SQLite, Postgres and MySQL. Results come back as dataframes, and — the important part — SQL cells participate in the reactive graph exactly like Python cells.

That last detail is what makes it more than syntactic sugar. A SQL query that depends on a Python variable re-runs when that variable changes. A Python cell that consumes a query result re-runs when the query does. The two languages become one dependency graph rather than two worlds joined by copy and paste.

For anyone whose work genuinely alternates between the two — which is most analytics work — this removes a persistent friction. The alternative in a conventional notebook is f-string interpolation into query text, which is both unpleasant to read and an easy way to write something you did not mean.

• Query dataframes directly with SQL, without loading them into a database first.
• Mix SQL and Python cells in one reactive graph, with dependencies tracked across both.
• Interactive elements — sliders, dropdowns, table selections — can feed query parameters.
• Results return as dataframes in your library of choice rather than as an opaque cursor.
• Supported engines include DuckDB, SQLite, Postgres and MySQL alongside in-memory dataframes.

Notebook, Script, App: One File

Because a marimo notebook is a Python module with a dependency graph, the same file supports three modes without conversion.

As a notebook it is an interactive editing environment. As a script it runs from the command line, in a scheduler or in CI, executing cells in dependency order. As an app, served with a single command, the code hides and the interactive elements remain — sliders, dropdowns, tables and plots become a small web application.

The third mode deserves attention because it collapses a workflow that normally spans two tools. The usual path from exploration to a shareable dashboard involves rewriting the analysis in a separate framework, which is enough work that it frequently does not happen and stakeholders receive a screenshot instead.

WASM export goes further still, producing a static HTML file that runs Python in the browser with no server at all. For teaching material, documentation and reproducible examples, a notebook someone can run by opening a link removes the environment setup that is usually the barrier.

Package handling closes the loop. marimo can serialise a notebook's requirements into the file itself and install them into an isolated sandbox on run, so a shared notebook carries its own dependencies rather than a hopeful README.

Getting A Real Feel For It In Ten Minutes

marimo is free and installs with pip, so evaluation costs nothing but time. The sequence below surfaces both the benefit and the constraint quickly, which is what you want before adopting anything.

The bar is step four. If the reactive re-run behaviour does not feel like a relief within the first few edits, the model is not going to suit how you work.

1. Install with pip install marimo and run marimo tutorial intro — the built-in tutorial is short and demonstrates reactivity better than any description.
2. Open one of your own existing analyses and rebuild the first twenty lines of it. Rebuilding beats converting for forming a judgement.
3. Deliberately hit the constraint: try to redefine one variable in two cells and read the error. Better to meet it now than in an hour.
4. Change an early cell and watch what re-runs downstream. This is the whole product, and either it feels like relief or it does not.
5. Add a slider bound to a parameter and watch the analysis update, then serve the same file with marimo run to see it as an app.
6. Commit the file and look at the diff in git. That view is the argument that usually convinces teams rather than individuals.

Where Jupyter Still Wins

An honest assessment has to account for why most people will keep using Jupyter, and the reasons are good ones.

Ecosystem is the largest, and hosted environments such as Deepnote have built collaboration on top of it. Fifteen years of extensions, integrations, teaching material and institutional muscle memory sit behind Jupyter. Every cloud provider supports its format natively, every data platform imports it, and every colleague already knows it.

Sequential execution also genuinely suits some work. A long-running training loop or an expensive query is something you want to run once and then build on, and reactivity means care is needed to avoid re-executing costly cells — marimo provides controls for this, but it is a thing you must now think about.

There is a collaboration consideration too. If your colleagues and your reviewers all work in Jupyter, a marimo notebook is an outlier in the repository, and the file-format advantage is partly a team benefit that only lands when the team adopts it.

The pragmatic position is that these are not mutually exclusive. Plenty of people explore in Jupyter and rebuild in marimo when something needs to become reliable, shareable or scheduled — then move the result into an editor such as Cursor when it graduates into a real codebase. The .py format makes that transition cheap in a way the reverse never was.

• Jupyter has the larger ecosystem, and every platform supports its format natively.
• Sequential execution suits expensive, run-once operations without extra thought.
• Your colleagues already know Jupyter, and format advantages are partly team-level.
• marimo's benefit compounds with team adoption — one person's notebooks still diff well, but code review changes only when everyone's do.

What marimo Costs

The notebook itself is open source and free. You install it with pip, run it locally, and no account is required at any point.

Alongside it sits molab, a hosted service for creating and sharing notebooks in the browser, comparable in shape to other cloud notebook offerings. The site also has a page addressed to enterprises, which is the usual signal that support and deployment arrangements are available commercially.

This is a healthy structure for a developer tool. The thing you depend on runs on your own machine and does not stop working if commercial priorities change, while the hosted convenience is optional.

The practical implication is that there is no reason not to try it. There is no trial to start, no card to enter and no account to create — the cost of evaluation is the ten minutes described above. We do not publish amounts for the hosted or commercial options; check the site for current terms.

marimo: The Technical Facts

Who Should Switch To marimo

Switch if

• You have been bitten by hidden state — a notebook that only ran because of a cell you had already deleted.
• Your team wants notebooks in code review, which the JSON format has effectively prevented for years.
• You regularly rewrite analyses as dashboards, and would rather serve the same file as an app.
• Your work alternates between SQL and Python and you are tired of interpolating queries into strings.
• You share notebooks with people who cannot reliably reproduce your environment, where WASM export removes the setup problem entirely.

Stay with Jupyter if

• Your work depends on Jupyter extensions or platform integrations that have no equivalent here.
• Your notebooks contain long-running training or expensive queries where automatic re-execution needs care you would rather not take.
• Your team all works in Jupyter and reviews Jupyter, so a lone marimo file is an outlier rather than an improvement.
• You rely on redefining variables freely across cells and do not want to change that habit.
• You need a managed collaborative environment with real-time multi-user editing as the primary requirement.