| | import marimo |
| |
|
| | __generated_with = "0.9.2" |
| | app = marimo.App() |
| |
|
| |
|
| | @app.cell |
| | def __(): |
| | import marimo as mo |
| |
|
| | mo.md("# Welcome to marimo! 🌊🍃") |
| | return (mo,) |
| |
|
| |
|
| | @app.cell |
| | def __(mo): |
| | slider = mo.ui.slider(1, 22) |
| | return (slider,) |
| |
|
| |
|
| | @app.cell |
| | def __(mo, slider): |
| | mo.md( |
| | f""" |
| | 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: {slider}. |
| | |
| | {"##" + "🍃" * slider.value} |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.accordion( |
| | { |
| | "Tip: disabling automatic execution": mo.md( |
| | rf""" |
| | 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. |
| | """ |
| | ) |
| | } |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | Tip: This is a tutorial notebook. You can create your own notebooks |
| | by entering `marimo edit` at the command line. |
| | """ |
| | ).callout() |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 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. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(changed, mo): |
| | ( |
| | mo.md( |
| | f""" |
| | **✨ Nice!** The value of `changed` is now {changed}. |
| | |
| | When you updated the value of the variable `changed`, marimo |
| | **reacted** by running this cell automatically, because this cell |
| | references the global variable `changed`. |
| | |
| | Reactivity ensures that your notebook state is always |
| | consistent, which is crucial for doing good science; it's also what |
| | enables marimo notebooks to double as tools and apps. |
| | """ |
| | ) |
| | if changed |
| | else mo.md( |
| | """ |
| | **🌊 See it in action.** In the next cell, change the value of the |
| | variable `changed` to `True`, then click the run button. |
| | """ |
| | ) |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell |
| | def __(): |
| | changed = False |
| | return (changed,) |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.accordion( |
| | { |
| | "Tip: execution order": ( |
| | """ |
| | 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. |
| | """ |
| | ) |
| | } |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | **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. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.accordion( |
| | { |
| | "Tip: encapsulation": ( |
| | """ |
| | By encapsulating logic in functions, classes, or Python modules, |
| | you can minimize the number of global variables in your notebook. |
| | """ |
| | ) |
| | } |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.accordion( |
| | { |
| | "Tip: private variables": ( |
| | """ |
| | Variables prefixed with an underscore are "private" to a cell, so |
| | they can be defined by multiple cells. |
| | """ |
| | ) |
| | } |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 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`. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell |
| | def __(mo): |
| | mo.md("""**🌊 Some UI elements.** Try interacting with the below elements.""") |
| | return |
| |
|
| |
|
| | @app.cell |
| | def __(mo): |
| | icon = mo.ui.dropdown(["🍃", "🌊", "✨"], value="🍃") |
| | return (icon,) |
| |
|
| |
|
| | @app.cell |
| | def __(icon, mo): |
| | repetitions = mo.ui.slider(1, 16, label=f"number of {icon.value}: ") |
| | return (repetitions,) |
| |
|
| |
|
| | @app.cell |
| | def __(icon, repetitions): |
| | icon, repetitions |
| | return |
| |
|
| |
|
| | @app.cell |
| | def __(icon, mo, repetitions): |
| | mo.md("# " + icon.value * repetitions.value) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 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). |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 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. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 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](https://www.github.com/marimo-team/marimo/tree/main/examples). |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | ## 6. The marimo editor |
| | |
| | Here are some tips to help you get started with the marimo editor. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell |
| | def __(mo, tips): |
| | mo.accordion(tips) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md("""## Finally, a fun fact""") |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(mo): |
| | mo.md( |
| | """ |
| | 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. |
| | """ |
| | ) |
| | return |
| |
|
| |
|
| | @app.cell(hide_code=True) |
| | def __(): |
| | tips = { |
| | "Saving": ( |
| | """ |
| | **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. |
| | """ |
| | ), |
| | "Running": ( |
| | """ |
| | 1. _Run a cell_ by clicking the play ( ▷ ) button on the top |
| | right of a cell, or by inputting `Ctrl/Cmd+Enter`. |
| | |
| | 2. _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. |
| | |
| | 3. _Run all stale cells_ by clicking the play ( ▷ ) button on |
| | the bottom right of the screen, or input `Ctrl/Cmd+Shift+r`. |
| | """ |
| | ), |
| | "Console Output": ( |
| | """ |
| | Console output (e.g., `print()` statements) is shown below a |
| | cell. |
| | """ |
| | ), |
| | "Creating, Moving, and Deleting Cells": ( |
| | """ |
| | 1. _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. |
| | |
| | 2. _Move_ a cell up or down by dragging on the handle to the |
| | right of the cell, which appears on mouse hover. |
| | |
| | 3. _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`. |
| | """ |
| | ), |
| | "Disabling Automatic Execution": ( |
| | """ |
| | 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. |
| | """ |
| | ), |
| | "Disabling Cells": ( |
| | """ |
| | 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. |
| | """ |
| | ), |
| | "Code Folding": ( |
| | """ |
| | 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. |
| | """ |
| | ), |
| | "Code Formatting": ( |
| | """ |
| | If you have [ruff](https://github.com/astral-sh/ruff) installed, |
| | you can format a cell with the keyboard shortcut `Ctrl/Cmd+b`. |
| | """ |
| | ), |
| | "Command Palette": ( |
| | """ |
| | Use `Ctrl/Cmd+k` to open the command palette. |
| | """ |
| | ), |
| | "Keyboard Shortcuts": ( |
| | """ |
| | Open the notebook menu (top-right) or input `Ctrl/Cmd+Shift+h` to |
| | view a list of all keyboard shortcuts. |
| | """ |
| | ), |
| | "Configuration": ( |
| | """ |
| | Configure the editor by clicking the gears icon near the top-right |
| | of the screen. |
| | """ |
| | ), |
| | } |
| | return (tips,) |
| |
|
| |
|
| | if __name__ == "__main__": |
| | app.run() |
| |
|
