Marimo

https://docs.marimo.io
Admin
Marimo is an open-source reactive Python notebook that allows for reproducible, maintainable, and...
Tokens:595,829
Snippets:5,245
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install marimo with uv and run tutorial

Source: https://docs.marimo.io/

Install marimo using uv and start the interactive tutorial. Requires uv.

```bash
uv add marimo && uv run marimo tutorial intro

```

--------------------------------

### Complete example with setup, function, class, and cell

Source: https://docs.marimo.io/guides/editor_features/watching

A complete runnable marimo notebook example that defines a setup block, a top-level function, a class definition, and a cell. The setup block imports numpy and defines a constant used by the function.

```python
import marimo

app = marimo.App()

with app.setup:
    # These symbols can be used by top-level functions and classes
    # (as well as by regular cells)
    import numpy as np

    CONSTANT: int = 1

@app.function
def my_function(x: np.ndarray):
    return np.mean(x) + CONSTANT

@app.class_definition
class MyClass:
    ...

@app.cell
def _():
    my_function(np.random.randn(2, 2))
    return

if __name__ == "__main__":
    app.run()
```

--------------------------------

### Install marimo and run tutorial

Source: https://docs.marimo.io/

Install marimo with pip or conda, then run the tutorial to get an overview of features.

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

```

--------------------------------

### mo.Thread start example

Source: https://docs.marimo.io/api/control_flow?q=

Example of creating and starting a mo.Thread with the target function.

```python
import marimo as mo

mo.Thread(target=target).start()
```

--------------------------------

### Install marimo with pip and run tutorial

Source: https://docs.marimo.io/

Install marimo using pip and start the interactive tutorial. Requires Python and pip.

```bash
pip install marimo && marimo tutorial intro

```

--------------------------------

### Install uv and start marimo with sandbox

Source: https://docs.marimo.io/guides/deploying/deploying_skypilot?q=

Inside the cluster, installs uv and starts marimo in edit mode with the --sandbox flag for isolated dependencies. The uvx command runs marimo without installing it in the environment, and --sandbox ensures notebook dependencies are installed separately for reproducibility.

```bash
pip install uv
uvx marimo edit --sandbox demo.py --port 8080 --token-password=supersecret

```

--------------------------------

### Start marimo with uv and sandbox

Source: https://docs.marimo.io/guides/deploying/deploying_skypilot

Installs uv and starts marimo in edit mode with sandboxed dependencies, listening on port 8080 with a token password. The --sandbox flag isolates notebook dependencies for reproducibility.

```bash
pip install uv
uvx marimo edit --sandbox demo.py --port 8080 --token-password=supersecret
```

--------------------------------

### Install marimo[sql] with uv

Source: https://docs.marimo.io/integrations/motherduck

Install the marimo SQL package with uv.

```bash
uv add "marimo[sql]"
```

--------------------------------

### Create a Dockerfile for a marimo notebook

Source: https://docs.marimo.io/guides/deploying/deploying_docker

Example Dockerfile for a marimo notebook. It uses Python 3.11-slim, installs uv for package management, copies requirements.txt and app.py, exposes port 8080, creates a non-root user, and runs the marimo app with the command `marimo run app.py --host 0.0.0.0 -p 8080`.

```Dockerfile
# syntax=docker/dockerfile:1.4

# Choose a python version that you know works with your application
FROM python:3.11-slim

# Install uv for fast package management
COPY --from=ghcr.io/astral-sh/uv:0.4.20 /uv /bin/uv
ENV UV_SYSTEM_PYTHON=1

WORKDIR /app

# Copy requirements file
COPY --link requirements.txt .

# Install the requirements using uv
RUN uv pip install -r requirements.txt

# Copy application files
COPY --link app.py .
# Uncomment the following line if you need to copy additional files
# COPY --link . .

EXPOSE 8080

# Create a non-root user and switch to it
RUN useradd -m app_user
USER app_user

CMD [ "marimo", "run", "app.py", "--host", "0.0.0.0", "-p", "8080" ]
```

--------------------------------

### Create dropdown of examples for pre-populated form

Source: https://docs.marimo.io/recipes?q=

Creates a dropdown with predefined example dictionaries. The selected example's values are used to pre-populate the form.

```python
examples = mo.ui.dropdown(
    options={
        "ex 1": {"t1": "hello", "t2": "world"},
        "ex 2": {"t1": "marimo", "t2": "notebook"},
    },
    value="ex 1",
    label="examples",
)

```

--------------------------------

### Pull and run Ollama models

Source: https://docs.marimo.io/guides/configuration/llm_providers?q=

Pull models with ollama pull, list installed models with ollama ls, start the server with ollama serve, and optionally run a model with ollama run. The example recommends codellama for code generation.

```bash
# View available models at https://ollama.com/library
ollama pull llama3.1
ollama pull codellama  # recommended for code generation

# View your installed models
ollama ls
```

```bash
ollama serve
# In another terminal, run a model (optional)
ollama run codellama
```

--------------------------------

### Verify uv installation with tutorial

Source: https://docs.marimo.io/getting_started/installation?q=

Run the marimo tutorial using uv to check if the installation worked.

```bash
uv run marimo tutorial intro

```

--------------------------------

### Run UI tutorial

Source: https://docs.marimo.io/getting_started/key_concepts

Run this command to launch the UI tutorial for interactive elements.

```bash
marimo tutorial ui
```

--------------------------------

### Run the Google Cloud Storage example

Source: https://docs.marimo.io/integrations/google_cloud_storage

Run the full Google Cloud Storage example notebook directly from the marimo repository.

```bash
marimo run https://raw.githubusercontent.com/marimo-team/marimo/main/examples/cloud/gcp/google_cloud_storage.py
```

--------------------------------

### Create a datetime picker with start and stop

Source: https://docs.marimo.io/api/inputs/dates?q=

Example of creating a datetime picker with a specific start and stop range.

```python
datetime_picker = mo.ui.datetime(
    start=dt.datetime(2023, 1, 1),
    stop=dt.datetime(2023, 12, 31, 23, 59, 59),
)
```

--------------------------------

### marimo tutorial intro command

Source: https://docs.marimo.io/cli?q=

Opens the intro tutorial for marimo. This is the first tutorial in the recommended sequence.

```bash
marimo tutorial intro

```

--------------------------------

### Verify Pixi installation with tutorial

Source: https://docs.marimo.io/getting_started/installation?q=

Run the marimo tutorial using Pixi to check if the installation worked.

```bash
pixi run marimo tutorial intro

```

--------------------------------

### Create date range picker with start and stop

Source: https://docs.marimo.io/api/inputs/dates

Creates a date range picker with a specific start and stop date. The example uses dt.date objects for the start and stop parameters.

```python
date_range = mo.ui.date_range(
    start=dt.date(2023, 1, 1), stop=dt.date(2023, 12, 31)
)
```

--------------------------------

### Solution: setup cell with imports

Source: https://docs.marimo.io/guides/lint_rules/rules/private_import_alias

Recommended approach: place imports in a setup cell or import-only cell, without private aliases.

```python
# In the notebook's setup cell
# or any import only cell.
import os
from collections import OrderedDict

```

--------------------------------

### Run the SQL tutorial

Source: https://docs.marimo.io/getting_started/key_concepts?q=

Command to launch the marimo SQL tutorial, which demonstrates querying dataframes and databases.

```bash
marimo tutorial sql

```

--------------------------------

### Run the layout tutorial

Source: https://docs.marimo.io/faq.html

Command to launch the marimo layout tutorial notebook, which demonstrates using hstack and vstack for arranging outputs.

```bash
marimo tutorial layout

```

--------------------------------

### start property

Source: https://docs.marimo.io/api/inputs/dates?q=

Get the minimum selectable date of the date range picker.

```APIDOC
## start property

### Description
Get the minimum selectable date. Returns the user-specified minimum date or 01-01-0001 if no start date was specified.

### Property
```
start: date
```

### Returns
- **date** - datetime.date: The start date.

```

--------------------------------

### Run the UI tutorial

Source: https://docs.marimo.io/getting_started/key_concepts?q=

Command to launch the marimo UI tutorial, which provides examples of interactive elements.

```bash
marimo tutorial ui

```

--------------------------------

### Example: Set plotting library theme based on app theme

Source: https://docs.marimo.io/api/app?q=

Example usage of app_meta() to get the current theme and conditionally set a plotting library's theme.

```python
import altair as alt
```

--------------------------------

### marimo run examples

Source: https://docs.marimo.io/cli?q=

Examples of running notebooks as apps, including running a single file, multiple folders, and passing arguments after --.

```bash
marimo run notebook.py
marimo run folder another_folder
marimo run app.py -- --arg value

```

--------------------------------

### Run the BigQuery example notebook

Source: https://docs.marimo.io/integrations/google_cloud_bigquery

Run the full Google Cloud BigQuery example notebook directly from the marimo repository.

```bash
marimo run https://raw.githubusercontent.com/marimo-team/marimo/main/examples/cloud/gcp/google_cloud_bigquery.py
```

--------------------------------

### Solution: os.getcwd call

Source: https://docs.marimo.io/guides/lint_rules/rules/private_import_alias?q=

Usage of `os.getcwd` after the import is placed in a setup or import-only cell. This is part of the solution example.

```python
os.getcwd()

```

--------------------------------

### Solution: os.listdir call

Source: https://docs.marimo.io/guides/lint_rules/rules/private_import_alias?q=

Usage of `os.listdir` after the import is placed in a setup or import-only cell. This is part of the solution example.

```python
os.listdir(".")

```

--------------------------------

### Run the full BigQuery example

Source: https://docs.marimo.io/integrations/google_cloud_bigquery?q=

Run the full example using Google Cloud BigQuery from the marimo repository.

```bash
marimo run https://raw.githubusercontent.com/marimo-team/marimo/main/examples/cloud/gcp/google_cloud_bigquery.py

```

--------------------------------

### Counter and danger button examples

Source: https://docs.marimo.io/api/inputs/button

Shows two button examples: a counter that increments its value on click using `on_click`, and a button with a danger style to convey intent. The counter starts at 0 and increments by 1 each click.

```python
# a counter implementation
counter_button = mo.ui.button(
    value=0, on_click=lambda value: value + 1, label="increment"
)

# adding intent
delete_button = mo.ui.button(
    label="Do not click",
    kind="danger",
)
```

--------------------------------

### Recommended tutorial sequence

Source: https://docs.marimo.io/cli?q=

Lists the recommended order of tutorials to follow to get the most out of marimo.

```bash
- intro
- dataflow
- ui
- markdown
- plots
- sql
- layout
- fileformat
- external-dependencies
- markdown-format
- for-jupyter-users

```

--------------------------------

### Import from local package

Source: https://docs.marimo.io/guides/package_management/importing_local_code

For code organized as a Python package, install it in the notebook's environment. The example shows a package layout and the import statement. An editable installation uses source files directly, avoiding reinstallation after changes.

```text
.
├── notebooks
│   └── my_notebook.py
├── pyproject.toml
└── src
    └── my_package
        ├── __init__.py
        └── my_module.py
```

```python
from my_package import my_module
```

--------------------------------

### List marimo tutorials with marimo tutorial --help

Source: https://docs.marimo.io/getting_started/quickstart

Lists all available marimo tutorials. Use this command to discover tutorial names before running one with `marimo tutorial <name>`.

```bash
marimo tutorial --help
```

--------------------------------

### Run SQL tutorial

Source: https://docs.marimo.io/getting_started/key_concepts

Run this command to launch the SQL tutorial for querying dataframes and databases.

```bash
marimo tutorial sql
```

--------------------------------

### marimo export pdf basic example

Source: https://docs.marimo.io/cli?q=

Exports a marimo notebook to a PDF file. Requires nbformat and nbconvert to be installed.

```bash
marimo export pdf notebook.py -o notebook.pdf
```

--------------------------------

### marimo app setup for admonitions example

Source: https://docs.marimo.io/examples/markdown/admonitions?q=

This is the full source code for the admonitions example. It includes the marimo app definition, a hidden cell with introductory markdown, and cells for each admonition. Paste this code into an empty cell in the marimo editor to create the cells.

```python
import marimo

__generated_with = "0.19.7"
app = marimo.App()


@app.cell(hide_code=True)
def _(mo):
    mo.md(r"""
    Use **admonitions** in markdown to bring attention to text. Here are some examples.
    """)
    return


@app.cell
def _(mo):
    mo.md("""
    /// admonition | Heads up.

    Here's some information.
    ///
    """)
    return


@app.cell
def _(mo):
    mo.md("""
    /// attention | Attention!

    This is important.
    ///
    """)
    return


@app.cell
def _():
    import marimo as mo

    return (mo,)


if __name__ == "__main__":
    app.run()

```

--------------------------------

### Open the dataflow tutorial

Source: https://docs.marimo.io/getting_started/key_concepts?q=

Run this command to open the dataflow tutorial, which demonstrates reactive execution and data flow in marimo notebooks.

```bash
marimo tutorial dataflow
```

--------------------------------

### Full example source code for admonitions.py

Source: https://docs.marimo.io/examples/markdown/admonitions

The complete source code for the admonitions example, which can be pasted into an empty marimo cell to recreate the notebook. It includes the marimo app setup, a hidden cell with introductory markdown, and two cells demonstrating admonitions.

```python
import marimo

__generated_with = "0.19.7"
app = marimo.App()


@app.cell(hide_code=True)
def _(mo):
    mo.md(r"""
    Use **admonitions** in markdown to bring attention to text. Here are some examples.
    """)
    return


@app.cell
def _(mo):
    mo.md("""
    /// admonition | Heads up.

    Here's some information.
    ///
    """)
    return


@app.cell
def _(mo):
    mo.md("""
    /// attention | Attention!

    This is important.
    ///
    """)
    return


@app.cell
def _():
    import marimo as mo

    return (mo,)


if __name__ == "__main__":
    app.run()
```

--------------------------------

### Basic usage of mo.image_compare

Source: https://docs.marimo.io/api/media/image_compare

Minimal example that compares two images using default settings. The slider starts at 50% and is oriented horizontally.

```python3
# Basic usage with two images
mo.image_compare(before_image="before.jpg", after_image="after.jpg")
```

--------------------------------

### Complete example with @app.function and @app.class_definition

Source: https://docs.marimo.io/guides/editor_features/watching?q=

A complete runnable example demonstrating the use of @app.function and @app.class_definition, along with an app.setup block for imports and constants.

```python
import marimo

app = marimo.App()

with app.setup:
    # These symbols can be used by top-level functions and classes
    # (as well as by regular cells)
    import numpy as np

    CONSTANT: int = 1

@app.function
def my_function(x: np.ndarray):
    return np.mean(x) + CONSTANT

@app.class_definition
class MyClass:
    ...

@app.cell
def _():
    my_function(np.random.randn(2, 2))
    return

if __name__ == "__main__":
    app.run()
```

--------------------------------

### Start Ollama server

Source: https://docs.marimo.io/guides/configuration/llm_providers

Start the Ollama server with `ollama serve` and optionally run a model in another terminal. If you get a "port already in use" error, close an existing Ollama instance (e.g., via the taskbar on Windows) before retrying.

```bash
ollama serve
# In another terminal, run a model (optional)
ollama run codellama
```

--------------------------------

### Run MotherDuck example notebook

Source: https://docs.marimo.io/integrations/motherduck

Open the MotherDuck example notebook in marimo edit.

```bash
marimo edit https://github.com/marimo-team/marimo/blob/main/examples/sql/connect_to_motherduck.py
```

--------------------------------

### marimo export html-wasm example

Source: https://docs.marimo.io/cli?q=

Exports a notebook as a WASM-powered standalone HTML file. The exported file runs in the browser via Pyodide without a local Python installation.

```bash
marimo export html-wasm notebook.py -o notebook.wasm.html

```

--------------------------------

### Run tutorials for outputs, plots, and layout

Source: https://docs.marimo.io/getting_started/key_concepts

Run these commands to launch tutorials on markdown, plots, and layout for visualizing outputs.

```bash
marimo tutorial markdown
marimo tutorial plots
marimo tutorial layout
```

--------------------------------

### Basic range slider with start, stop, step, and value

Source: https://docs.marimo.io/api/inputs/range_slider

Creates a range slider with start=1, stop=10, step=2, and initial value [2, 6]. This is the basic usage example.

```python
range_slider = mo.ui.range_slider(
    start=1, stop=10, step=2, value=[2, 6]
)
```

--------------------------------

### Install marimo with uv (minimal)

Source: https://docs.marimo.io/getting_started/installation

Adds marimo to a project using uv. Run 'uv init' first for a new project. Verify with 'uv run marimo tutorial intro'.

```bash
uv add marimo
```

```bash
uv run marimo tutorial intro
```

--------------------------------

### Full iframe example with all recommended settings

Source: https://docs.marimo.io/guides/publishing/embedding

Complete copy-pasteable example with all recommended settings. Uses `?embed=true&mode=read` for a read-only viewable notebook, includes the extra `allow-downloads-without-user-activation` sandbox token, and adds inline styling for a border and rounded corners.

```html
<iframe
  src="https://marimo.app/github/marimo-team/gallery-examples/blob/main/notebooks/math/cellular-automaton-art.py/wasm?embed=true&mode=read"
  sandbox="allow-scripts allow-same-origin allow-downloads allow-popups allow-forms allow-downloads-without-user-activation"
  allow="microphone"
  allowfullscreen
  width="100%"
  height="600"
  style="border: 1px solid #ddd; border-radius: 8px;"
></iframe>
```

--------------------------------

### Output matplotlib plot using current Axes

Source: https://docs.marimo.io/guides/working_with_data/plotting?q=

Include the Axes object as the last expression in a cell to display the plot in the output area. The example uses plt.gca() to get the current Axes.

```python
plt.plot([1, 2])
# plt.gca() gets the current `Axes`
plt.gca()

```

--------------------------------

### Use prebuilt marimo container in a Dockerfile

Source: https://docs.marimo.io/guides/deploying/prebuilt_containers

Use this Dockerfile to base your image on the `latest-sql` container, install additional dependencies, and start the marimo server with `marimo edit` on port 8080 without a token.

```dockerfile
FROM ghcr.io/marimo-team/marimo:latest-sql

# Install any additional dependencies here

CMD ["marimo", "edit", "--no-token", "-p", "8080", "--host", "0.0.0.0"]
```

--------------------------------

### SkyPilot job YAML configuration

Source: https://docs.marimo.io/guides/deploying/deploying_skypilot

SkyPilot job configuration file that specifies resources (V100 GPU), working directory, environment variables, setup command to install uv, and the run command to execute the notebook.

```yaml
# marimo-job.yaml
name: marimo-demo

# Specify resources for this job
resources:
  accelerators: V100:1

# Point to the folder containing your marimo notebook
workdir: .

# Environment variables (e.g., for W&B, HuggingFace)
envs:
  WANDB_API_KEY: ${WANDB_API_KEY}

# Install uv
setup: pip install uv

# Run the notebook with arguments
run: uv run demo.py --hello world --demo works --lr 0.01
```

--------------------------------

### Example uv library project layout

Source: https://docs.marimo.io/guides/package_management/projects

Example layout of a uv library project created with `uv init --lib my-library`. The `src` directory contains the package source and `notebooks` contains the notebook file.

```text
my-library/
├── pyproject.toml
├── uv.lock
├── src/
│   └── my_library/
│       └── __init__.py
└── notebooks/
    └── analysis.py
```

--------------------------------

### Basic markdown example notebook source

Source: https://docs.marimo.io/examples/outputs/basic_markdown

Complete marimo notebook source code that creates a markdown cell using mo.md(). The code includes the necessary imports and app setup. The markdown cell is hidden in the UI (hide_code=True) and instructs users to create a Markdown cell via the button or action menu.

```python
import marimo

__generated_with = "0.19.7"
app = marimo.App()


@app.cell
def _():
    import marimo as mo

    return (mo,)


@app.cell(hide_code=True)
def _(mo):
    mo.md("""
    Create a "Markdown" cell by clicking the `Markdown` button below,
    or through the cell action menu.

    Markdown is represented as Python under-the-hood, using the `mo.md()`
    function — so you'll need to import marimo as mo into your notebook
    first!
    """)
    return


if __name__ == "__main__":
    app.run()

```

--------------------------------

### marimo tutorial usage

Source: https://docs.marimo.io/cli?q=

Shows the usage syntax for the `marimo tutorial` command, including the list of available tutorials.

```bash
marimo tutorial [OPTIONS] {intro|dataflow|ui|markdown|plots|sql|layout|filefor
                mat|external-dependencies|markdown-format|for-jupyter-users}

```
Tokens:
Raw