Cell

marimo.Cell dataclass

Cell(_name: str, _cell: CellImpl, _app: InternalApp | None = None, _pytest_reserved: set[str] = set(), _test_allowed: bool = False, _expected_signature: Optional[tuple[str, ...]] = None)

An executable notebook cell

Cells are the fundamental unit of execution in marimo. They represent a single unit of execution, which can be run independently and reused across notebooks.

Cells are defined using the @app.cell decorator, which registers the function as a cell in marimo.

For example:

@app.cell
def my_cell(mo, x, y):
    z = x + y
    mo.md(f"The value of z is {z}")  # This will output markdown
    return (z,)

Cells can be invoked as functions, and picked up by external frameworks (like pytest if their name starts with test_). However, consider implementing reusable functions (@app.function) in your notebook for granular control of the output.

A Cell object can also be executed without arguments via its run() method, which returns the cell's last expression (output) and a mapping from its defined names to its values.

For example:

from my_notebook import my_cell

output, definitions = my_cell.run()

Cells can be named via the marimo editor in the browser, or by changing the cell's function name in the notebook file.

See the documentation of run for info and examples.

defs property

defs: set[str]

The definitions made by this cell

name property

name: str

refs property

refs: set[str]

The references that this cell takes as input

run

run(**refs: Any) -> tuple[Any, Mapping[str, Any]] | Awaitable[tuple[Any, Mapping[str, Any]]]

Run this cell and return its visual output and definitions.

Use this method to run named cells and retrieve their output and definitions. This lets you reuse cells defined in one notebook in another notebook or Python file. It also makes it possible to write and execute unit tests for notebook cells using a test framework like pytest.

Examples:

marimo cells can be given names either through the editor cell menu or by manually changing the function name in the notebook file. For example, consider a notebook notebook.py:

import marimo

app = marimo.App()


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

    return (mo,)


@app.cell
def __():
    x = 0
    y = 1
    return (x, y)


@app.cell
def add(mo, x, y):
    z = x + y
    mo.md(f"The value of z is {z}")
    return (z,)


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

To reuse the add cell in another notebook, you'd simply write:

from notebook import add

# `output` is the markdown rendered by `add`
# defs["z"] == `1`
output, defs = add.run()

When run is called without arguments, it automatically computes the values that the cell depends on (in this case, mo, x, and y). You can override these values by providing any subset of them as keyword arguments. For example,

# defs["z"] == 4
output, defs = add.run(x=2, y=2)

Defined UI Elements

If the cell's output has UI elements that are in defs, interacting with the output in the frontend will trigger reactive execution of cells that reference the defs object. For example, if output has a slider defined by the cell, then scrubbing the slider will cause cells that reference defs to run.

Async cells

If this cell is a coroutine function (starting with async), or if any of its ancestors are coroutine functions, then you'll need to await the result: output, defs = await cell.run(). You can check whether the result is an awaitable using:

from collections.abc import Awaitable

ret = cell.run()
if isinstance(ret, Awaitable):
    output, defs = await ret
else:
    output, defs = ret

PARAMETER	DESCRIPTION
**refs	You may pass values for any of this cell's references as keyword arguments. marimo will automatically compute values for any refs that are not provided by executing the parent cells that compute them. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
tuple[Any, Mapping[str, Any]] | Awaitable[tuple[Any, Mapping[str, Any]]]	tuple (output, defs), or an awaitable of the same: output is the cell's last expression and defs is a Mapping from the cell's defined names to their values.