marimo: A Reactive Python Notebook Environment
marimo-team/marimo
marimo is a reactive Python notebook that reruns dependent cells automatically and stores everything as a plain .py file instead of JSON. Reach for it if you're tired of stale variables and out-of-order execution wrecking a Jupyter session, or if you want to ship the same notebook as a script or a web app without rewriting it. Skip it if your team is deep into existing .ipynb tooling and extensions that marimo doesn't support yet.
Understanding marimo's Core Purpose
marimo is an open-source Python notebook where each cell is a node in a dependency graph: running or deleting a cell automatically reruns or clears everything that depends on it. Notebooks are saved as plain .py files, so they diff cleanly in git and can run as scripts, pytest targets, or a web app via marimo run. It also has built-in SQL cells and an AI-native editor for pairing with coding agents.
Addressing Traditional Notebook Challenges
Jupyter notebooks let you run cells in any order, so the variables sitting in memory can silently drift from what's on the page. Delete a cell that defined df, and df is still alive in the kernel. Every downstream cell keeps working — until it doesn't. Jupyter also stores notebooks as JSON, so a one-line code change produces a diff full of execution-count and output noise that's painful to review in a pull request. marimo's dependency-graph runtime and .py file format target those two failure modes directly, not notebooks being messy in general.
Key Capabilities of marimo
- ✓Reactive runtime: editing a cell automatically reruns every cell that references its variables, and deleting a cell scrubs its variables from memory instead of leaving hidden state behind.
- ✓Notebooks are stored as pure Python .py files, so they diff cleanly in git and can be imported like a normal module.
- ✓Built-in SQL cells query dataframes, databases, warehouses, lakehouses, CSVs, or Google Sheets and hand back the result as a Python dataframe — still pure Python underneath.
- ✓UI elements like sliders, dropdowns, dataframe transformers, and chat interfaces are bound directly to Python values with no callback functions to wire up.
- ✓A lazy runtime mode marks affected cells as stale instead of re-running them automatically, so you don't accidentally trigger an expensive cell.
- ✓Built-in package management can install packages on import and serialize requirements inside the notebook file, auto-installing them into an isolated venv sandbox.
- ✓AI-native editor: pair with coding agents such as Claude Code, Codex, or OpenCode via marimo pair, or use the built-in AI assistant with your own API keys or local models.
- ✓Notebooks run as pytest targets, export to HTML, and run in the browser via WASM.
Practical Applications for marimo
- •Exploratory data analysis where you page through, search, filter, and sort dataframes with millions of rows without writing extra code.
- •Turning a research notebook into a deployable app with marimo run, hiding the source and only exposing the UI elements.
- •Reproducible experiments you want to version in git and review as normal Python diffs rather than JSON blobs.
- •Data-aware AI workflows where an agent needs to see your variables in memory to generate the next cell.
- •Teaching or documentation notebooks that mix dynamic markdown parametrized by live Python variables with executable code.
Getting Started with marimo
Install with `pip install marimo` or `conda install -c conda-forge marimo`, then run `marimo tutorial intro` to open the built-in walkthrough. If you want SQL cells and AI completion out of the box, install the extras with `pip install "marimo[recommended]"` instead of the bare package. There's also molab, a free hosted notebook the README compares to Google Colab, if you'd rather skip local installation entirely.
Working with marimo Notebooks
Run `marimo edit` to create or edit a notebook in the reactive editor. When a notebook is ready to share, `marimo run your_notebook.py` serves it as a web app with the code hidden and uneditable, while `python your_notebook.py` executes the same file as a plain script from the command line. To bring existing work over, `marimo convert your_notebook.ipynb > your_notebook.py` turns a Jupyter notebook into a marimo one, or you can use the web-based converter instead of the CLI.
Strengths
- ✓You stop babysitting execution order — the dependency graph does that job, and it's the single biggest daily-use improvement over Jupyter.
- ✓Code review on a notebook finally looks like code review on anything else, because the file is Python, not a JSON blob with embedded outputs.
- ✓Running the same file as an app, a script, and an editable notebook means you're not maintaining three versions of the same analysis.
- ✓The lazy runtime mode is a real safety valve for notebooks with expensive cells — you get correctness guarantees without accidentally re-running a slow query.
Considerations for Using marimo
- △Cell order in the file doesn't drive execution — variable references do — which means notebooks converted from Jupyter or written by someone new to the reactive model can behave unexpectedly until you internalize that rule.
- △The SQL cells and AI completion features live behind the `marimo[recommended]` extras rather than the base install, so a plain `pip install marimo` doesn't give you the full feature set the README highlights, out of the box.
- △Reactive re-execution is a different mental model from Jupyter's run-any-cell-any-time flow, and existing Jupyter-specific extensions or workflows built around that flexibility won't carry over directly.
Comparing marimo to Other Tools
Common Questions About marimo
marimo removes the hidden state that plagues tools like Jupyter: its reactive runtime reruns or clears every cell downstream of a change, and because notebooks are stored as .py files instead of JSON, they produce clean, reviewable git diffs.
marimo executes cells in an order determined by variable references rather than their position on the page, and deleting a cell removes its variables from memory immediately, so re-running the notebook top to bottom always reproduces the same program state.
marimo notebooks can be deployed as interactive web apps: running `marimo run your_notebook.py` serves the notebook with its Python code hidden and uneditable, exposing only the UI elements like sliders and dataframe filters.
marimo is released under the Apache-2.0 license, according to its GitHub repository.
marimo pairs directly with coding agents such as Claude Code, Codex, or OpenCode through marimo pair, and its editor has a built-in AI assistant that can see your in-memory variables, with support for custom system prompts, your own API keys, or local models.
marimo can convert Jupyter notebooks automatically with `marimo convert your_notebook.ipynb > your_notebook.py`, or through the web-based converter at marimo.io/convert, if you'd rather not use the CLI.
Who should try it — and who should skip
Reach for marimo if you're a Python developer doing iterative data work — EDA, model experiments, or a small internal app — and you're annoyed by Jupyter's execution-order bugs or by reviewing notebook diffs in a pull request. Skip it if your workflow depends on a specific Jupyter extension, a large existing library of .ipynb files you don't want to convert, or a team that's already standardized on Jupyter and isn't looking to relearn a reactive execution model for the sake of cleaner git diffs.