marimo

目次

• 編集と検証の徹底
• 重要な概念
• セルの構造
• 編集ルール
• コア CLI コマンド
• エクスポートコマンド
• データと可視化
• デバッグのワークフロー
• よくある問題
• 追加リソース

Marimo リアクティブノートブック

Marimo は、セルが DAG を形成し、依存関係が変更されると自動実行されるリアクティブな Python ノートブックです。ノートブックは純粋な .py ファイルとして保存されます。

編集と検証の徹底

絶対ルール #1：セルのデコレーターやシグネチャは絶対に変更しない

編集できるのは @app.cell 関数の本体内のコードだけです。これは譲れないルールです。

絶対に変更しないこと：

• セルのデコレーター（@app.cell）
• 関数のシグネチャ（def _(deps):）
• return 文の構造（末尾のカンマが必要です）

必ず確認すること：

• 使用するすべての変数が関数のパラメーターに含まれている
• 作成したすべての変数が return 文に含まれている
• 1 つの値を返す場合は末尾にカンマを付ける：return var,

絶対ルール #2：出力を検証せずに実行できたと主張しない

marimo ノートブックが動作すると主張する前に、必ず次の手順を実行してください。

1. 構文と構造を検証する：marimo check notebook.py
2. 出力付きで実行する：marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
3. 検証する：notebook-debug スキルの検証チェックリストを使用する
4. 成功を主張する：検証に合格した後に限る

これは譲れないルールです。実行して出力を確認せずに「ノートブックは動作します」と主張するのは、ユーザーに嘘をつくことです。

正当化の一覧 - こう考えたら作業を止めてください：

言い訳	実際のところ	代わりに行うこと
「marimo check に合格したから、動作する」	構文チェック ≠ 実行時の正しさ	--include-outputs を付けて実行し、出力を確認する
「ほんの小さな変更だから、何も壊れない」	リアクティブな仕組みでは、小さな変更があらゆる箇所に伝播します	全体を実行して検証する
「依存関係の追跡は marimo に任せればよい」	正しく動作することの検証は依然として必要です	出力が期待どおりか確認する
「関数のシグネチャは正しそうだ」	deps や return の誤りは、気づかないうちにリアクティブな動作を壊します	すべての変数がパラメーターと return の両方に含まれているか検証する
「関数のシグネチャを変更してもよい」	marimo の依存関係検出が壊れます	関数本体の内側だけを編集する
「変数は return しなくても使える」	依存するセルで NameError が発生します	作成したすべての変数を return する
「1 つの値を返す場合、末尾のカンマは省略できる」	Python は return var を値の返却として扱うため、アンパックが壊れます	1 つの値を返す場合は return var, を使用する

危険な兆候 - こう考えたらすぐに作業を止めてください：

• 「この変数を関数のシグネチャに追加しよう」→ いいえ。シグネチャは marimo が管理します。
• 「marimo check だけ実行して終わりにしよう」→ いいえ。出力付きでの実行が必要です。
• 「コードは正しそうだ」→ いいえ。marimo のリアクティブな動作を実行時に検証する必要があります。
• 「この変数を別のセルで再定義できる」→ いいえ。1 つの変数は 1 つのセルに置きます。

編集チェックリスト

marimo を編集する前に、毎回次の項目を確認してください。

構造の検証：

• @app.cell 関数の本体の中だけを編集する
• デコレーターやシグネチャを変更しない
• 使用する変数がすべて関数のパラメーターに含まれていることを確認する
• 作成した変数がすべて戻り値に含まれていることを確認する
• 戻り値が 1 つの場合は末尾にカンマを付ける
• セル間で変数が再定義されていないことを確認する

構文の検証：

• marimo check notebook.py を実行する
• 構文エラーが報告されていないことを確認する
• 未定義変数の警告がないことを確認する
• 再定義の警告がないことを確認する

実行時の検証：

• marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs を実行する
• エクスポートが成功したこと（終了コード 0）を確認する
• 出力された ipynb が存在し、空ではないことを確認する
• notebook-debug の検証チェックリストを適用する
• どのセルにもトレースバックがないことを確認する
• すべてのセルが実行されていること（execution_count が null でないこと）を確認する
• 出力が期待どおりであることを確認する

すべてのチェックに合格した場合に限り：

• 「ノートブックは動作します」と報告する

ゲート関数：Marimo の検証

marimo のタスクでは、必ず次の手順に従ってください。

1. EDIT     → Modify code inside @app.cell function bodies only
2. CHECK    → marimo check notebook.py
3. EXECUTE  → marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
4. INSPECT  → Use notebook-debug verification
5. VERIFY   → Outputs match expectations
6. CLAIM    → "Notebook works" only after all gates passed

検証ゲートを決して省略しないでください。 marimo のリアクティブな仕組みにより、変更が予測できない形で伝播するためです。

誠実な説明

--include-outputs を指定して marimo ノートブックを実行し、結果を確認せずに動作すると報告するのは、嘘をつくことです。

構文チェックやコードの確認だけでは、リアクティブな実行が正しく行われることの証明にはなりません。ユーザーが期待しているのは、依存関係が適切に追跡され、すべてのセルが正しく実行されるノートブックです。

主なコンセプト

• リアクティブな実行：依存関係が変更されると、セルが自動的に更新されます
• 隠れた状態がない：各変数は必ず 1 つのセルだけで定義します
• 純粋な Python：.py ファイルを使用するため、バージョン管理に適しています
• セル構造：@app.cell デコレーターパターン

セル構造

import marimo

app = marimo.App()

@app.cell
def _(pl):  # Dependencies as parameters
    df = pl.read_csv("data.csv")
    return df,  # Trailing comma required for single return

@app.cell
def _(df, pl):
    summary = df.describe()
    filtered = df.filter(pl.col("value") > 0)
    return summary, filtered  # Multiple returns

編集ルール

• @app.cell 関数の中のコードだけを編集します
• セルのデコレーターや関数シグネチャは決して変更しません
• セル間で変数を再定義することはできません
• 使用する変数はすべて、定義元のセルから返す必要があります
• Markdown セル：$ は必ずバッククォートで囲みます — mo.md("Cost: $50") のように記述し、mo.md("Cost: $50") とはしません

主な CLI コマンド

コマンド	目的
marimo edit notebook.py	marimo：インタラクティブな開発のために、ブラウザーエディターでノートブックを開きます
marimo run notebook.py	marimo：ノートブックを実行可能なアプリとして実行します
marimo check notebook.py	marimo：実行せずにノートブックの構造と構文を検証します
marimo convert notebook.ipynb	marimo：Jupyter ノートブックを marimo 形式に変換します

エクスポートコマンド

# marimo: Export to ipynb with code only
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb

# marimo: Export to ipynb with outputs (runs notebook first)
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

# marimo: Export to HTML (runs notebook by default)
marimo export html notebook.py -o __marimo__/notebook.html

# marimo: Export to HTML with auto-refresh on changes (live preview)
marimo export html notebook.py -o __marimo__/notebook.html --watch

重要な違い： HTML エクスポートでは、デフォルトでノートブックが実行されます。ipynb エクスポートでは実行されないため、実行して出力を保存するには --include-outputs を使用します。

ヒント： すべてのエクスポート（ipynb、html）には __marimo__/ フォルダーを使用してください。エディターはそこに自動保存できます。

データと可視化

• パフォーマンスを優先して pandas より polars を使用します
• インタラクティブなウィジェットには mo.ui を使用します
• SQL セル：mo.sql(df, "SELECT * FROM df")
• Markdown の表示：mo.md("# Heading")

デバッグのワークフロー

1. 実行前の検証：

# scripts: Validate notebook syntax and cell structure
scripts/check_notebook.sh notebook.py

構文チェック、marimo による検証、セル構造の概要を 1 つのコマンドで実行します。

2. 実行時エラー： 出力付きでエクスポートしてから、notebook-debug スキルを使用します：

# marimo: Export to ipynb with outputs for inspection
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

よくある問題

問題	対処方法
変数の再定義	変数名を変更するか、セルを統合します
循環依存	セルを統合するか、構成を変更して循環を解消します
戻り値がない	末尾にカンマを付けて return var, を追加します
インポートが利用できない	インポート用のセルからモジュールを返していることを確認します

追加リソース

リファレンスファイル

詳細なパターンや高度なテクニックについては、以下を参照してください：

• references/reactivity.md - DAG の実行、変数のルール、依存関係の検出パターン
• references/debugging.md - エラーパターン、ランタイムのデバッグ、環境固有の問題
• references/widgets.md - インタラクティブな UI コンポーネントと mo.ui のパターン
• references/sql.md - SQL セルとデータベース統合のテクニック

例

examples/ に動作する例があります：

• examples/basic_notebook.py - marimo ノートブックの最小構成
• examples/data_analysis.py - データの読み込み、フィルタリング、可視化のパターン
• examples/interactive_widgets.py - インタラクティブな UI コンポーネントの使用例

スクリプト

検証ユーティリティは scripts/ にあります：

• scripts/check_notebook.sh - 主な検証：構文チェック、marimo による検証、セル構造の概要
• scripts/get_cell_map.py - セルのメタデータを抽出（check_notebook.sh から呼び出されます）

関連スキル

• notebook-debug - トレースバックと出力の確認による、実行済み ipynb ファイルのデバッグ