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 ノートブックの実行

# スクリプトとして実行 (非対話的、テスト用)
uv run <notebook.py>

# ブラウザで対話的に実行
uv run marimo run <notebook.py>

# 対話的に編集
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 を使用しない

良いパターン

# ウィジェットは常に表示
@app.cell
def _(ScatterWidget, mo):
    scatter_widget = mo.ui.anywidget(ScatterWidget())
    scatter_widget
    return (scatter_widget,)

# データソースのみモードに基づいて変更
@app.cell
def _(is_script_mode, make_moons, scatter_widget, np, torch):
    if is_script_mode:
        # テスト用に合成データを使用
        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:
        # 対話モードではウィジェットデータを使用
        X, y = scatter_widget.widget.data_as_X_y
        # ... データ処理 ...
    return X_data, y_data, data_error

# スライダーは常に表示 - 両モードで .value を使用
@app.cell
def _(mo):
    lr_slider = mo.ui.slider(start=0.001, stop=0.1, value=0.01)
    lr_slider
    return (lr_slider,)

# スクリプトモードでは自動実行、対話モードではボタンを待機
@app.cell
def _(is_script_mode, train_button, lr_slider, run_training, X_data, y_data):
    if is_script_mode:
        # スライダーのデフォルト値で自動実行
        results = run_training(X_data, y_data, lr=lr_slider.value)
    else:
        # ボタンクリックを待機
        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 のリアクティビティはセルが依存関係の準備ができた時のみ実行されることを意味します。不要な保護を追加しないでください:

# 悪い例 - if ステートメントがチャートの表示を妨げる
@app.cell
def _(plt, training_results):
    if training_results:  # 間違い - これをしないでください
        fig, ax = plt.subplots()
        ax.plot(training_results['losses'])
        fig
    return

# 良い例 - marimo に依存関係を処理させる
@app.cell
def _(plt, training_results):
    fig, ax = plt.subplots()
    ax.plot(training_results['losses'])
    fig
    return

セルは training_results に値が入るまで実行されません。

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

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

# 悪い例 - 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}"

# 良い例 - 何かが間違っていれば失敗させる
@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 はセルの最終式のみをレンダリングします。インデントされた、または条件付きの式はレンダリングされません:

# 悪い例 - インデントされた式はレンダリングされない
@app.cell
def _(mo, condition):
    if condition:
        mo.md("This won't show!")  # 間違い - インデント済み
    return

# 良い例 - 最終式がレンダリングされる
@app.cell
def _(mo, condition):
    result = mo.md("Shown!") if condition else mo.md("Also shown!")
    result  # これは最終式なのでレンダリングされる
    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>

追加リソース

• 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 を参照してください