marimo README

The project's README from github.com/marimo-team/marimo. As one markdown file: README.md.

A reactive Python notebook that's reproducible, git-friendly, and deployable as scripts or apps.

Docs · Discord · Examples · Gallery · YouTube

English | 繁體中文 | 简体中文 | 日本語 | Español

discord Pepy Total Downloads Conda Downloads

marimo is a reactive Python notebook: run a cell or interact with a UI element, and marimo automatically runs dependent cells (or marks them as stale), keeping code and outputs consistent. marimo notebooks are stored as pure Python (with first-class SQL support), executable as scripts, and deployable as apps.

Highlights.

pip install marimo && marimo tutorial intro

Get started instantly with molab, our free online notebook. Or jump to the quickstart for a primer on our CLI.

A reactive programming environment

marimo guarantees your notebook 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.

Compatible with expensive notebooks. marimo lets you configure the runtime to be lazy, marking affected cells as stale instead of automatically running them. This gives you guarantees on program state while preventing accidental execution of expensive cells.

Synchronized UI elements. Interact with UI elements like sliders, dropdowns, dataframe transformers, and chat interfaces, and the cells that use them are automatically re-run with their latest values.

Interactive dataframes. Page through, search, filter, and sort millions of rows blazingly fast, no code required.

Generate cells with data-aware AI. Collaborate on marimo notebooks with your favorite agent, such as Claude Code, Codex, or OpenCode, using marimo pair. Or, generate code in the marimo editor with an AI assistant that is highly specialized for working with data, with context about your variables in memory. Customize the system prompt, bring your own API keys, or use local models.

Query data with SQL. Build SQL queries that depend on Python values and execute them against dataframes, databases, lakehouses, CSVs, Google Sheets, or anything else using our built-in SQL engine, which returns the result as a Python dataframe.

Your notebooks are still pure Python, even if they use SQL.

Dynamic markdown. Use markdown parametrized by Python variables to tell dynamic stories that depend on Python data.

Built-in package management. marimo has built-in support for all major package managers, letting you install packages on import. marimo can even serialize package requirements in notebook files, and auto install them in isolated venv sandboxes.

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.

Performant runtime. marimo runs only those cells that need to be run by statically analyzing your code.

Batteries-included. marimo comes with GitHub Copilot, AI assistants, Ruff code formatting, HTML export, fast code completion, a VS Code extension, a PyCharm plugin, an interactive dataframe viewer, and many more quality-of-life features.

Quickstart

The marimo concepts playlist on our YouTube channel gives an overview of many features.

Installation. In a terminal, run

pip install marimo  # or conda install -c conda-forge marimo
marimo tutorial intro

To install with additional dependencies that unlock SQL cells, AI completion, and more, run

pip install "marimo[recommended]"

Create notebooks.

Create or edit notebooks with

marimo edit

Run apps. Run your notebook as a web app, with Python code hidden and uneditable:

marimo run your_notebook.py

Execute as scripts. Execute a notebook as a script at the command line:

python your_notebook.py

Automatically convert Jupyter notebooks. Automatically convert Jupyter notebooks to marimo notebooks with the CLI

marimo convert your_notebook.ipynb > your_notebook.py

or use our web interface.

Tutorials. List all tutorials:

marimo tutorial --help

Share cloud-based notebooks. Use molab, a cloud-based marimo notebook service similar to Google Colab, to create and share notebook links.

Questions?

See the FAQ at our docs.

Learn more

marimo is easy to get started with, with lots of room for power users. For example, here's an embedding visualizer made in marimo (try the notebook live on molab!):

Check out our docs, usage examples, and our gallery to learn more.

Tutorial Inputs Plots Layout

Contributing

We appreciate all contributions! You don't need to be an expert to help out. Please see CONTRIBUTING.md for more details on how to get started.

Questions? Reach out to us on Discord.

Community

We're building a community. Come hang out with us!

A NumFOCUS affiliated project. marimo is a core part of the broader Python ecosystem and is a member of the NumFOCUS community, which includes projects such as NumPy, SciPy, and Matplotlib.

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 experiment with code and share it; to learn computational science and teach it.

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.

Finally, we would like to acknowledge Bennet Meyers and David Chassin for believing in marimo from the very beginning: this work was supported in part by U.S. DOE Office of Critical Minerals and Energy Innovation (CMEI) Integrated Energy Systems Office (IESO), Agreement 34368.

marimo (marimo-team/marimo)

reactive
Searching Database…

23.2K ·GitHub
What is this?A reactive Python notebook: run a cell or touch a UI element and dependent cells re-run automatically, keeping code and outputs consistent. Notebooks are pure Python files that can run as scripts or deploy as web apps.
How is it different from Jupyter?Jupyter stores notebooks as JSON and hidden state builds up as you re-run cells by hand. marimo executes cells in a deterministic order driven by variable references, scrubs deleted cells from memory, and saves git-friendly .py files.
How do I get it running?Install with pip, then 'marimo edit' opens a notebook in your browser and 'marimo run' serves it as a web app. For zero setup, try it on molab, the project's free cloud notebook service.
What do I need installed besides Python?Just Python. The base pip install covers notebooks; an extended install unlocks SQL cells and AI completion. Built-in package management installs packages on import and can auto-install requirements in isolated venv sandboxes.
If one cell takes an hour, will every small edit re-run the whole notebook?No — you can set the runtime to lazy mode, where affected cells are marked stale instead of executed, so slow cells only run when you explicitly run them.
Is this aimed at data scientists, or Python developers in general?Anyone doing computational work in Python — data science, machine learning, research, teaching. marimo is a NumFOCUS-affiliated project meant for doing research, sharing experiments, and teaching computational science.
Does it matter which OS I'm on?It's pip-installed Python, so macOS, Linux, and Windows all work, with the editor UI served in your browser. Deployed notebooks can even run entirely in the browser via WASM.
What does AI-native mean here — is my code sent off to a cloud model?Only if you opt in. You can pair coding agents like Claude Code, Codex, or OpenCode with notebooks via marimo pair, or use the built-in assistant with your own API keys or local models.
Is it Python-only, or can I query data with SQL?SQL is first-class: a built-in engine queries dataframes, databases, warehouses, lakehouses, CSVs, and Google Sheets, returning results as Python dataframes. Queries can depend on Python values, and the saved notebook stays pure Python.
Can I share a notebook with someone who shouldn't see the code?Yes — 'marimo run' deploys it as an interactive web app with the Python hidden and uneditable. UI elements like sliders, dropdowns, and dataframe transformers keep working without callbacks, and notebooks can also be exported as slides.
Can notebook code be reused and tested like a normal Python module?Yes — functions and classes can be imported from one notebook into another, and you can run pytest on notebooks.
I have a pile of old Jupyter notebooks — do I have to rewrite them?No — a CLI command and a web interface convert Jupyter notebooks to marimo automatically.
Size
252.4 MB
Stars
23.2K
Age
3y
Commits · 90 Days