Welcome to marimo! ππ
import%20marimo%20as%20mo%0A%0Amo.md(%22%23%20Welcome%20to%20marimo!%20%F0%9F%8C%8A%F0%9F%8D%83%22)
slider%20%3D%20mo.ui.slider(1%2C%2022)
marimo is a reactive Python notebook.
This means that unlike traditional notebooks, marimo notebooks run
automatically when you modify them or
interact with UI elements, like this slider: .
π
mo.md(%0A%20%20%20%20f%22%22%22%0A%20%20%20%20marimo%20is%20a%20**reactive**%20Python%20notebook.%0A%0A%20%20%20%20This%20means%20that%20unlike%20traditional%20notebooks%2C%20marimo%20notebooks%20**run%0A%20%20%20%20automatically**%20when%20you%20modify%20them%20or%0A%20%20%20%20interact%20with%20UI%20elements%2C%20like%20this%20slider%3A%20%7Bslider%7D.%0A%0A%20%20%20%20%7B%22%23%23%22%20%2B%20%22%F0%9F%8D%83%22%20*%20slider.value%7D%0A%20%20%20%20%22%22%22%0A)
marimo lets you disable automatic execution: just go into the
notebook settings and set
"Runtime > On Cell Change" to "lazy".
When the runtime is lazy, after running a cell, marimo marks its
descendants as stale instead of automatically running them. The
lazy runtime puts you in control over when cells are run, while
still giving guarantees about the notebook state.
mo.accordion(%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22Tip%3A%20disabling%20automatic%20execution%22%3A%20mo.md(%0A%20%20%20%20%20%20%20%20%20%20%20%20rf%22%22%22%0A%20%20%20%20%20%20%20%20marimo%20lets%20you%20disable%20automatic%20execution%3A%20just%20go%20into%20the%0A%20%20%20%20%20%20%20%20notebook%20settings%20and%20set%0A%0A%20%20%20%20%20%20%20%20%22Runtime%20%3E%20On%20Cell%20Change%22%20to%20%22lazy%22.%0A%0A%20%20%20%20%20%20%20%20When%20the%20runtime%20is%20lazy%2C%20after%20running%20a%20cell%2C%20marimo%20marks%20its%0A%20%20%20%20%20%20%20%20descendants%20as%20stale%20instead%20of%20automatically%20running%20them.%20The%0A%20%20%20%20%20%20%20%20lazy%20runtime%20puts%20you%20in%20control%20over%20when%20cells%20are%20run%2C%20while%0A%20%20%20%20%20%20%20%20still%20giving%20guarantees%20about%20the%20notebook%20state.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20)%0A%20%20%20%20%7D%0A)
mo.md(%0A%20%20%20%20%22%22%22%0A%20%20%20%20Tip%3A%20This%20is%20a%20tutorial%20notebook.%20You%20can%20create%20your%20own%20notebooks%0A%20%20%20%20by%20entering%20%60marimo%20edit%60%20at%20the%20command%20line.%0A%20%20%20%20%22%22%22%0A).callout()
1. Reactive execution
A marimo notebook is made up of small blocks of Python code called cells.
marimo reads your cells and models the dependencies among them: whenever a cell that defines a global variable is run, marimo automatically runs all cells that reference that variable.
Reactivity keeps your program state and outputs in sync with your code, making for a dynamic programming environment that prevents bugs before they happen.
π See it in action. In the next cell, change the value of the
variable changed
to True
, then click the run button.
(%0A%20%20%20%20mo.md(%0A%20%20%20%20%20%20%20%20f%22%22%22%0A%20%20%20%20%20%20%20%20**%E2%9C%A8%20Nice!**%20The%20value%20of%20%60changed%60%20is%20now%20%7Bchanged%7D.%0A%0A%20%20%20%20%20%20%20%20When%20you%20updated%20the%20value%20of%20the%20variable%20%60changed%60%2C%20marimo%0A%20%20%20%20%20%20%20%20**reacted**%20by%20running%20this%20cell%20automatically%2C%20because%20this%20cell%0A%20%20%20%20%20%20%20%20references%20the%20global%20variable%20%60changed%60.%0A%0A%20%20%20%20%20%20%20%20Reactivity%20ensures%20that%20your%20notebook%20state%20is%20always%0A%20%20%20%20%20%20%20%20consistent%2C%20which%20is%20crucial%20for%20doing%20good%20science%3B%20it's%20also%20what%0A%20%20%20%20%20%20%20%20enables%20marimo%20notebooks%20to%20double%20as%20tools%20and%20%20apps.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%0A%20%20%20%20if%20changed%0A%20%20%20%20else%20mo.md(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20**%F0%9F%8C%8A%20See%20it%20in%20action.**%20In%20the%20next%20cell%2C%20change%20the%20value%20of%20the%0A%20%20%20%20%20%20%20%20variable%20%20%60changed%60%20to%20%60True%60%2C%20then%20click%20the%20run%20button.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%0A)
changed%20%3D%20False
The order of cells on the page has no bearing on
the order in which cells are executed: marimo knows that a cell
reading a variable must run after the cell that defines it. This
frees you to organize your code in the way that makes the most
sense for you.
mo.accordion(%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22Tip%3A%20execution%20order%22%3A%20(%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20%20%20%20%20The%20order%20of%20cells%20on%20the%20page%20has%20no%20bearing%20on%0A%20%20%20%20%20%20%20%20%20%20%20%20the%20order%20in%20which%20cells%20are%20executed%3A%20marimo%20knows%20that%20a%20cell%0A%20%20%20%20%20%20%20%20%20%20%20%20reading%20a%20variable%20must%20run%20after%20the%20cell%20that%20%20defines%20it.%20This%0A%20%20%20%20%20%20%20%20%20%20%20%20frees%20you%20to%20organize%20your%20code%20in%20the%20way%20that%20makes%20the%20most%0A%20%20%20%20%20%20%20%20%20%20%20%20sense%20for%20you.%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20)%0A%20%20%20%20%7D%0A)
Global names must be unique. To enable reactivity, marimo imposes a constraint on how names appear in cells: no two cells may define the same variable.
By encapsulating logic in functions, classes, or Python modules,
you can minimize the number of global variables in your notebook.
mo.accordion(%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22Tip%3A%20encapsulation%22%3A%20(%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20%20%20%20%20By%20encapsulating%20logic%20in%20functions%2C%20classes%2C%20or%20Python%20modules%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20you%20can%20minimize%20the%20number%20of%20global%20variables%20in%20your%20notebook.%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20)%0A%20%20%20%20%7D%0A)
Variables prefixed with an underscore are "private" to a cell, so
they can be defined by multiple cells.
mo.accordion(%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%22Tip%3A%20private%20variables%22%3A%20(%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20%20%20%20%20Variables%20prefixed%20with%20an%20underscore%20are%20%22private%22%20to%20a%20cell%2C%20so%0A%20%20%20%20%20%20%20%20%20%20%20%20they%20can%20be%20defined%20by%20multiple%20cells.%0A%20%20%20%20%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20)%0A%20%20%20%20%7D%0A)
2. UI elements
Cells can output interactive UI elements. Interacting with a UI element automatically triggers notebook execution: when you interact with a UI element, its value is sent back to Python, and every cell that references that element is re-run.
marimo provides a library of UI elements to choose from under marimo.ui
. π Some UI elements. Try interacting with the below elements.
icon%20%3D%20mo.ui.dropdown(%5B%22%F0%9F%8D%83%22%2C%20%22%F0%9F%8C%8A%22%2C%20%22%E2%9C%A8%22%5D%2C%20value%3D%22%F0%9F%8D%83%22)
repetitions%20%3D%20mo.ui.slider(1%2C%2016%2C%20label%3Df%22number%20of%20%7Bicon.value%7D%3A%20%22)
icon%2C%20repetitions
π
mo.md(%22%23%20%22%20%2B%20icon.value%20*%20repetitions.value)
3. marimo is just Python
marimo cells parse Python (and only Python), and marimo notebooks are stored as pure Python files β outputs are not included. Thereβs no magical syntax.
The Python files generated by marimo are:
- easily versioned with git, yielding minimal diffs
- legible for both humans and machines
- formattable using your tool of choice,
- usable as Python scripts, with UI elements taking their default values, and
- importable by other modules (more on that in the future). ## 4. Running notebooks as apps
marimo notebooks can double as apps. Click the app window icon in the bottom-right to see this notebook in βapp view.β
Serve a notebook as an app with marimo run
at the command-line. Of course, you can use marimo just to level-up your notebooking, without ever making apps. ## 5. The marimo
command-line tool
Creating and editing notebooks. Use
marimo edit
in a terminal to start the marimo notebook server. From here you can create a new notebook or edit existing ones.
Running as apps. Use
marimo run notebook.py
to start a webserver that serves your notebook as an app in read-only mode, with code cells hidden.
Convert a Jupyter notebook. Convert a Jupyter notebook to a marimo notebook using marimo convert
:
marimo convert your_notebook.ipynb > your_app.py
Tutorials. marimo comes packaged with tutorials:
dataflow
: more on marimoβs automatic execution
ui
: how to use UI elements
markdown
: how to write markdown, with interpolated values and LaTeX
plots
: how plotting works in marimo
sql
: how to use SQL
layout
: layout elements in marimo
fileformat
: how marimoβs file format works
markdown-format
: for using .md
files in marimo
for-jupyter-users
: if you are coming from Jupyter
Start a tutorial with marimo tutorial
; for example,
marimo tutorial dataflow
In addition to tutorials, we have examples in our our GitHub repo. ## 6. The marimo editor
Here are some tips to help you get started with the marimo editor.
Saving
-
Name your app using the box at the top of the screen, or
with
Ctrl/Cmd+s
. You can also create a named app at the
command line, e.g., marimo edit app_name.py
.
-
Save by clicking the save icon on the bottom right, or by
inputting
Ctrl/Cmd+s
. By default marimo is configured
to autosave.
-
Run a cell by clicking the play ( β· ) button on the top
right of a cell, or by inputting
Ctrl/Cmd+Enter
.
-
Run a stale cell by clicking the yellow run button on the
right of the cell, or by inputting
Ctrl/Cmd+Enter
. A cell is
stale when its code has been modified but not run.
-
Run all stale cells by clicking the play ( β· ) button on
the bottom right of the screen, or input
Ctrl/Cmd+Shift+r
.
Console output (e.g., print()
statements) is shown below a
cell.
-
Create a new cell above or below a given one by clicking
the plus button to the left of the cell, which appears on
mouse hover.
-
Move a cell up or down by dragging on the handle to the
right of the cell, which appears on mouse hover.
-
Delete a cell by clicking the trash bin icon. Bring it
back by clicking the undo button on the bottom right of the
screen, or with
Ctrl/Cmd+Shift+z
.
Via the notebook settings (gear icon) or footer panel, you
can disable automatic execution. This is helpful when
working with expensive notebooks or notebooks that have
side-effects like database transactions.
You can disable a cell via the cell context menu.
marimo will never run a disabled cell or any cells that depend on it.
This can help prevent accidental execution of expensive computations
when editing a notebook.
You can collapse or fold the code in a cell by clicking the arrow
icons in the line number column to the left, or by using keyboard
shortcuts.
Use the command palette (Ctrl/Cmd+k
) or a keyboard shortcut to
quickly fold or unfold all cells.
If you have ruff installed,
you can format a cell with the keyboard shortcut Ctrl/Cmd+b
. Use Ctrl/Cmd+k
to open the command palette.
Open the notebook menu (top-right) or input Ctrl/Cmd+Shift+h
to
view a list of all keyboard shortcuts.
Configure the editor by clicking the gears icon near the top-right
of the screen.
You can leave Marimo & shut down the server by clicking the
circled X at the top right of the screen and responding
to the prompt.
πΎ Be sure to save your work first!
mo.accordion(tips)
Finally, a fun fact
The name βmarimoβ is a reference to a type of algae that, under the right conditions, clumps together to form a small sphere called a βmarimo moss ballβ. Made of just strands of algae, these beloved assemblages are greater than the sum of their parts.
tips%20%3D%20%7B%0A%20%20%20%20%22Saving%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20**Saving**%0A%0A%20%20%20%20%20%20%20%20-%20_Name_%20your%20app%20using%20the%20box%20at%20the%20top%20of%20the%20screen%2C%20or%0A%20%20%20%20%20%20%20%20%20%20with%20%60Ctrl%2FCmd%2Bs%60.%20You%20can%20also%20create%20a%20named%20app%20at%20the%0A%20%20%20%20%20%20%20%20%20%20command%20line%2C%20e.g.%2C%20%60marimo%20edit%20app_name.py%60.%0A%0A%20%20%20%20%20%20%20%20-%20_Save_%20by%20clicking%20the%20save%20icon%20on%20the%20bottom%20right%2C%20or%20by%0A%20%20%20%20%20%20%20%20%20%20inputting%20%60Ctrl%2FCmd%2Bs%60.%20By%20default%20marimo%20is%20configured%0A%20%20%20%20%20%20%20%20%20%20to%20autosave.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Running%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%201.%20_Run%20a%20cell_%20by%20clicking%20the%20play%20(%20%E2%96%B7%20)%20button%20on%20the%20top%0A%20%20%20%20%20%20%20%20right%20of%20a%20cell%2C%20or%20by%20inputting%20%60Ctrl%2FCmd%2BEnter%60.%0A%0A%20%20%20%20%20%20%20%202.%20_Run%20a%20stale%20cell_%20%20by%20clicking%20the%20yellow%20run%20button%20on%20the%0A%20%20%20%20%20%20%20%20right%20of%20the%20cell%2C%20or%20by%20inputting%20%60Ctrl%2FCmd%2BEnter%60.%20A%20cell%20is%0A%20%20%20%20%20%20%20%20stale%20when%20its%20code%20has%20been%20modified%20but%20not%20run.%0A%0A%20%20%20%20%20%20%20%203.%20_Run%20all%20stale%20cells_%20by%20clicking%20the%20play%20(%20%E2%96%B7%20)%20button%20on%0A%20%20%20%20%20%20%20%20the%20bottom%20right%20of%20the%20screen%2C%20or%20input%20%60Ctrl%2FCmd%2BShift%2Br%60.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Console%20Output%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20Console%20output%20(e.g.%2C%20%60print()%60%20statements)%20is%20shown%20below%20a%0A%20%20%20%20%20%20%20%20cell.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Creating%2C%20Moving%2C%20and%20Deleting%20Cells%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%201.%20_Create_%20a%20new%20cell%20above%20or%20below%20a%20given%20one%20by%20clicking%0A%20%20%20%20%20%20%20%20%20%20%20%20the%20plus%20button%20to%20the%20left%20of%20the%20cell%2C%20which%20appears%20on%0A%20%20%20%20%20%20%20%20%20%20%20%20mouse%20hover.%0A%0A%20%20%20%20%20%20%20%202.%20_Move_%20a%20cell%20up%20or%20down%20by%20dragging%20on%20the%20handle%20to%20the%20%0A%20%20%20%20%20%20%20%20%20%20%20%20right%20of%20the%20cell%2C%20which%20appears%20on%20mouse%20hover.%0A%0A%20%20%20%20%20%20%20%203.%20_Delete_%20a%20cell%20by%20clicking%20the%20trash%20bin%20icon.%20Bring%20it%0A%20%20%20%20%20%20%20%20%20%20%20%20back%20by%20clicking%20the%20undo%20button%20on%20the%20bottom%20right%20of%20the%0A%20%20%20%20%20%20%20%20%20%20%20%20screen%2C%20or%20with%20%60Ctrl%2FCmd%2BShift%2Bz%60.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Disabling%20Automatic%20Execution%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20Via%20the%20notebook%20settings%20(gear%20icon)%20or%20footer%20panel%2C%20you%0A%20%20%20%20%20%20%20%20can%20disable%20automatic%20execution.%20This%20is%20helpful%20when%0A%20%20%20%20%20%20%20%20working%20with%20expensive%20notebooks%20or%20notebooks%20that%20have%0A%20%20%20%20%20%20%20%20side-effects%20like%20database%20transactions.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Disabling%20Cells%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20You%20can%20disable%20a%20cell%20via%20the%20cell%20context%20menu.%0A%20%20%20%20%20%20%20%20marimo%20will%20never%20run%20a%20disabled%20cell%20or%20any%20cells%20that%20depend%20on%20it.%0A%20%20%20%20%20%20%20%20This%20can%20help%20prevent%20accidental%20execution%20of%20expensive%20computations%0A%20%20%20%20%20%20%20%20when%20editing%20a%20notebook.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Code%20Folding%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20You%20can%20collapse%20or%20fold%20the%20code%20in%20a%20cell%20by%20clicking%20the%20arrow%0A%20%20%20%20%20%20%20%20icons%20in%20the%20line%20number%20column%20to%20the%20left%2C%20or%20by%20using%20keyboard%0A%20%20%20%20%20%20%20%20shortcuts.%0A%0A%20%20%20%20%20%20%20%20Use%20the%20command%20palette%20(%60Ctrl%2FCmd%2Bk%60)%20or%20a%20keyboard%20shortcut%20to%0A%20%20%20%20%20%20%20%20quickly%20fold%20or%20unfold%20all%20cells.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Code%20Formatting%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20If%20you%20have%20%5Bruff%5D(https%3A%2F%2Fgithub.com%2Fastral-sh%2Fruff)%20installed%2C%0A%20%20%20%20%20%20%20%20you%20can%20format%20a%20cell%20with%20the%20keyboard%20shortcut%20%60Ctrl%2FCmd%2Bb%60.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Command%20Palette%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20Use%20%60Ctrl%2FCmd%2Bk%60%20to%20open%20the%20command%20palette.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Keyboard%20Shortcuts%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20%20Open%20the%20notebook%20menu%20(top-right)%20or%20input%20%60Ctrl%2FCmd%2BShift%2Bh%60%20to%0A%20%20%20%20%20%20%20%20view%20a%20list%20of%20all%20keyboard%20shortcuts.%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Configuration%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20Configure%20the%20editor%20by%20clicking%20the%20gears%20icon%20near%20the%20top-right%0A%20%20%20%20%20%20%20of%20the%20screen.%0A%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%20%20%20%20%22Exit%20%26%20Shutdown%22%3A%20(%0A%20%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20%20%20%20You%20can%20leave%20Marimo%20%26%20shut%20down%20the%20server%20by%20clicking%20the%0A%20%20%20%20%20%20%20circled%20X%20at%20the%20top%20right%20of%20the%20screen%20and%20responding%0A%20%20%20%20%20%20%20to%20the%20prompt.%20%0A%0A%20%20%20%20%20%20%20%3Afloppy_disk%3A%20_Be%20sure%20to%20save%20your%20work%20first!_%20%0A%20%20%20%20%20%20%20%22%22%22%0A%20%20%20%20)%2C%0A%7D
Back to top