marimo-notebook

marimo ノートブックに関する注意事項

marimo は Jupyter が JSON を使用するのとは異なり、Python でノートブックを作成します。以下はノートブックの例です。

# /// script
# dependencies = [
#     "marimo",
#     "numpy==2.4.3",
# ]
# requires-python = ">=3.14"
# ///

import marimo

__generated_with = "0.20.4"
app = marimo.App(width="medium")


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

    return mo, np


@app.cell
def _():
    print("hello world")
    return


@app.cell
def _(np, slider):
    np.array([1,2,3]) + slider.value
    return


@app.cell
def _(mo):
    slider = mo.ui.slider(1, 10, 1, label="number to add")
    slider
    return (slider,)


@app.cell
def _():
    return


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

ノートブックが、関数でセルの内容を表す構造になっていることに注目してください。各セルは @app.cell デコレーターで定義され、関数の入力と出力がセルの入力と出力になります。通常、marimo がセル間の依存関係を自動的に処理します。

Marimo ノートブックの実行

# Run as script (non-interactive, for testing)
uv run <notebook.py>

# Run interactively in browser
uv run marimo run <notebook.py>

# Edit interactively
uv run marimo edit <notebook.py>

スクリプトモードの検出

mo.app_meta().mode == "script" を使用して、CLI モードか対話モードかを検出します。

@app.cell
def _(mo):
    is_script_mode = mo.app_meta().mode == "script"
    return (is_script_mode,)

重要な原則：シンプルに保つ

UI 要素は常にすべて表示します。 スクリプトモードではデータソースのみを変更します。

• スライダー、ボタン、ウィジェットは常に作成して表示します
• スクリプトモードでは、ユーザーの入力を待つ代わりに合成データやデフォルトのデータを使用します
• すべてを if not is_script_mode 条件で囲まないでください
• 通常の制御フローに try/except を使用しないでください

適切なパターン

# Always show the widget
@app.cell
def _(ScatterWidget, mo):
    scatter_widget = mo.ui.anywidget(ScatterWidget())
    scatter_widget
    return (scatter_widget,)

# Only change data source based on mode
@app.cell
def _(is_script_mode, make_moons, scatter_widget, np, torch):
    if is_script_mode:
        # Use synthetic data for testing
        X, y = make_moons(n_samples=200, noise=0.2)
        X_data = torch.tensor(X, dtype=torch.float32)
        y_data = torch.tensor(y)
        data_error = None
    else:
        # Use widget data in interactive mode
        X, y = scatter_widget.widget.data_as_X_y
        # ... process data ...
    return X_data, y_data, data_error

# Always show sliders - use their .value in both modes
@app.cell
def _(mo):
    lr_slider = mo.ui.slider(start=0.001, stop=0.1, value=0.01)
    lr_slider
    return (lr_slider,)

# Auto-run in script mode, wait for button in interactive
@app.cell
def _(is_script_mode, train_button, lr_slider, run_training, X_data, y_data):
    if is_script_mode:
        # Auto-run with slider defaults
        results = run_training(X_data, y_data, lr=lr_slider.value)
    else:
        # Wait for button click
        if train_button.value:
            results = run_training(X_data, y_data, lr=lr_slider.value)
    return (results,)

状態とリアクティブ性

セル間の変数によって、ほとんどのユースケースではノートブックのリアクティブ性が定まります。特別な状態管理は必要ありません。セル間でオブジェクトを変更せず（例：my_list.append()）、代わりに新しいオブジェクトを作成してください。双方向の UI 同期や、コールバック状態の蓄積が必要な場合を除き、mo.state() は使用しないでください。詳しくは STATE.md を参照してください。

セルを if 文で囲まない

marimo のリアクティブ性により、依存関係の準備が整ってからセルが実行されます。不要なガードを追加しないでください。

# BAD - the if statement prevents the chart from showing
@app.cell
def _(plt, training_results):
    if training_results:  # WRONG - don't do this
        fig, ax = plt.subplots()
        ax.plot(training_results['losses'])
        fig
    return

# GOOD - let marimo handle the dependency
@app.cell
def _(plt, training_results):
    fig, ax = plt.subplots()
    ax.plot(training_results['losses'])
    fig
    return

いずれにしても、training_results に値が設定されるまでセルは実行されません。

制御フローに try/except を使用しない

特定の予期される例外に対処する場合を除き、コードを try/except ブロックで囲まないでください。エラーはそのまま表面化させてください。

# BAD - hiding errors behind try/except
@app.cell
def _(scatter_widget, np, torch):
    try:
        X, y = scatter_widget.widget.data_as_X_y
        X = np.array(X, dtype=np.float32)
        # ...
    except Exception as e:
        return None, None, f"Error: {e}"

# GOOD - let it fail if something is wrong
@app.cell
def _(scatter_widget, np, torch):
    X, y = scatter_widget.widget.data_as_X_y
    X = np.array(X, dtype=np.float32)
    # ...

try/except を使用するのは、次の場合に限ります。

• 特定の既知の例外型に対処する場合
• 通常の動作で例外が予期される場合（例：ファイルが見つからない）
• 意味のある復旧処理がある場合

セル出力の描画

marimo はセルの最後の式のみを描画します。インデントされた式や条件付きの式は描画されません。

# BAD - indented expression won't render
@app.cell
def _(mo, condition):
    if condition:
        mo.md("This won't show!")  # WRONG - indented
    return

# GOOD - final expression renders
@app.cell
def _(mo, condition):
    result = mo.md("Shown!") if condition else mo.md("Also shown!")
    result  # This renders because it's the final expression
    return

PEP 723 の依存関係

marimo edit --sandbox で作成したノートブックでは、これらの依存関係がファイルの先頭に自動的に追加されます。ただし、ノートブックを作成する際にも、これらが存在することを確認するのが望ましいです。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "marimo",
#     "torch>=2.0.0",
# ]
# ///

marimo check

ノートブックを作成する際は、ノートブックが実行できるかどうかを確認することが重要です。そのため marimo には、よくある間違いを見つけるリンターとして機能する check コマンドが用意されています。

uvx marimo check <notebook.py>

ノートブックをユーザーに返す前に、必ずこれらのチェックを実行してください。

重要：アンダースコアを接頭辞に付けた変数を多用しがちです。使用する変数は、多くても 1～2 個にしてください。marimo でセル全体に接頭辞を付ける代わりに、新しい変数の作成を検討してください。

API ドキュメント

ユーザーから marimo の関数を使うよう明確に求められた場合は、次の方法でローカルからドキュメントを確認できます。

uv --with marimo run python -c "import marimo as mo; help(mo.ui.form)"

テスト

デフォルトでは、marimo はノートブック内のテストを検出して実行します。 オプションの pytest 依存関係が存在する場合、marimo はテストコードのみで構成されるセル、つまり名前が test_ で始まる関数を含むセルに対して pytest を実行します。 ユーザーからテストの追加を依頼された場合は、pytest の依存関係が追加されていることと、テストコードのみを含むセルがあることを確認してください。

pytest を使ったテストについて詳しくは、PYTEST.md を参照してください。

テストを追加したら、ノートブックに対してコマンドラインから pytest を実行できます。

pytest <notebook.py>

追加リソース

• width=columns で実行する marimo ノートブックについては、SQL.md を参照してください
• marimo での SQL の使用については、SQL.md を参照してください
• marimo の UI 要素については、UI.md を参照してください
• 関数／クラスをトップレベルのインポートとして公開する方法については、TOP-LEVEL-IMPORTS.md を参照してください
• ノートブックのエクスポート（PDF、HTML、Markdown など）については、EXPORTS.md を参照してください
• 状態管理とリアクティビティについては、STATE.md を参照してください
• marimo ノートブックのデプロイについては、DEPLOYMENT.md を参照してください
• anywidget を使ったカスタムのインタラクティブウィジェットについては、ANYWIDGET.md を参照してください
• 外部編集と --watch モードについては、WATCHING.md を参照してください
• 処理コストの高いノートブック（キャッシュ、遅延評価、mo.stop）については、EXPENSIVE.md を参照してください
• 設定（pyproject.toml、marimo.toml）については、CONFIGURATION.md を参照してください
• リアクティビティモデル（DAG、変数のスコープ、ミューテーション）については、REACTIVITY.md を参照してください