February 5, 2024

Introducing marimo

Akshay

@akshaykagrawal

marimo is an open-source reactive notebook for Python that’s reproducible, git-friendly (stored as Python files), executable as a script, and deployable as an app.

Traditional Python notebooks excel when used as a visual Python console. But their REPL-like programming model, in which cells can be executed out of order and state persists hidden from view, is problematic for the important tasks that they are used for today.

When you’re running computational experiments, training models, transforming data, and even building tools and pipelines, it’s crucial to be able to reproduce, reuse, version, and share your work as real software artifacts.

The problem with notebooks

If you’ve ever used Jupyter notebooks, you’ve almost certainly spent hours chasing down bugs due to hidden state — where a variable no longer exists in your code, but still exists in program memory. You’ve almost certainly received a notebook from a colleague that utterly failed to reproduce — when you ran it, you saw outputs different from the ones serialized in the notebook (or maybe it didn’t run at all!). You may have tried, and failed, to version your notebooks with git — you changed just one line of code, but the git diff showed an enormous change in the notebook’s JSON representation. You likely have directories cluttered with dozens of UntitledXX.ipynb files — some of which are mostly copies of other notebooks, since it wasn’t really possible to reuse your notebook code as you would regular Python. And you may even have built rudimentary tools in notebooks — but you had no way to make them usable by an audience that didn’t know Python.

These problems with Jupyter notebooks are well-known and well-documented. For example, see a recent study by JetBrains that analyzed 10 million notebooks on GitHub and found that 36 percent of them weren’t reproducible, as well as Joel Grus’ famous talk on why he dislikes notebooks.

Despite these shortcomings, notebooks are still widely used, and for good reason: the ability to iterate on data and models in memory, visualizing outputs along the way, provides a huge productivity boost over re-executing a script from beginning to end each time you change a line of code.

Building a new programming environment

I can empathize with the pains felt by notebook users because I’ve felt them myself.

My background is in both computer systems — I worked as an engineer at Google Brain, where I worked on TensorFlow and its runtime — and machine learning research — I have a PhD in machine learning and optimization from Stanford university.

I worked with Jupyter notebooks almost daily in my research; having seen engineers invent the future at Google Brain, I was convinced that there must be a way to build a better programming environment for working with data — one that made data tangible and actionable, while also solving the long list of problems that notebooks suffer from.

With feedback from beta users in research institutions and tech companies, I worked for over a year to build marimo, a reactive notebook for Python that’s reproducible, git-friendly (stored as pure Python files), executable as a script, and deployable as an app.

marimo is now ready for broader use: it’s open source and available at GitHub. It’s also available on PyPI. Get started with:

pip install marimo && marimo tutorial intro

Or to create a new notebook, run:

marimo edit

A reactive programming environment

marimo guarantees your code, outputs, and program state are consistent. This solves many problems associated with traditional notebooks like Jupyter.

A reactive programming environment. Run a cell and marimo reacts by automatically running the cells that reference its variables, eliminating the error-prone task of manually re-running cells. Delete a cell and marimo scrubs its variables from program memory, eliminating hidden state.

reactivity

Deterministic execution order. Notebooks are executed in a deterministic order, based on variable references instead of cells’ positions on the page. Organize your notebooks to best fit the stories you’d like to tell.

UI elements. marimo comes with UI elements like sliders, a dataframe transformer, and interactive plots that are automatically synchronized with Python [3]. Interact with an element and the cells that use it are automatically re-run with its latest value. Reactivity makes these UI elements more useful and ergonomic than Jupyter’s ipywidgets.

slider

Run apps. Every marimo notebook can be run as an interactive read-only web app, with code hidden: just use marimo run your_notebook.py.

app

Execute as scripts. Because marimo notebooks are saved as Python files, you can run them as Python scripts.

Performant runtime. marimo runs only those cells that need to be run by statically analyzing your code. You can optionally disable expensive cells to prevent them from automatically running.

Batteries-included. marimo comes with GitHub Copilot, Black code formatting, HTML export, fast code completion, a VS Code extension, and many more quality-of-life features.

Inspiration

marimo is a reinvention of the Python notebook as a reproducible, interactive, and shareable Python program, instead of an error-prone JSON scratchpad.

We believe that the tools we use shape the way we think — better tools, for better minds. With marimo, we hope to provide the Python community with a better programming environment to do research and communicate it; to run computational experiments and scale them; to learn computer science and teach it.

embedding

Our inspiration comes from many places and projects, especially Pluto.jl, ObservableHQ, and Bret Victor’s essays. marimo is part of a greater movement toward reactive dataflow programming. From IPyflow, streamlit, TensorFlow, PyTorch, JAX, and React, the ideas of functional, declarative, and reactive programming are transforming a broad range of tools for the better.

Join the marimo community

We’re a team of just two developers, and we’re just getting started. If you’re interested in helping shape marimo’s future, here are some ways you can get involved:

See all posts