marimo

marimo

概要

marimo は、ノートブックを再現可能で、インタラクティブかつ共有可能な Python プログラムとして再構築する、オープンソースのリアクティブな Python ノートブックです。従来の Jupyter ノートブックとは異なり、marimo のノートブックには次の特徴があります。

• 純粋な .py ファイルとして保存されます（Git に適しており、JSON は不要です）
• リアクティブに実行されます（スプレッドシートのように動作します）
• スクリプトとして実行したり、Web アプリとしてデプロイしたりできます
• 依存関係を自動的に追跡し、バグを防ぎます

インストール

pip install marimo                    # Basic
pip install marimo[recommended]       # With extras
pip install marimo[sql]               # With SQL support

marimo tutorial intro                 # Start tutorial

CLI コマンド

# Edit
marimo edit                           # New notebook
marimo edit notebook.py               # Edit existing
marimo edit --watch --sandbox         # Watch files, isolate deps

# Run as app
marimo run notebook.py                # Read-only app
marimo run notebook.py --watch        # Auto-reload on changes

# Run as script
python notebook.py

# Create from prompt
marimo new "analyze sales data"

# Convert
marimo convert notebook.ipynb -o notebook.py

# Export
marimo export html notebook.py -o output.html
marimo export html-wasm notebook.py -o output.html  # Browser-executable

主な概念

リアクティビティ

セルを実行すると、そのセルに依存するすべてのセルが自動的に実行されます。実行順序はセルの位置ではなく、変数の依存関係（DAG）によって決まります。

セルのルール

1. 各グローバル変数は、必ず1つのセルでのみ定義してください
2. list.append() のような変更は追跡されないため、再代入してください
3. 変更が必要な場合は、宣言と同じセル内で行ってください

ファイル形式

ノートブックは、marimo デコレーターを使った純粋な Python ファイルです。

import marimo
app = marimo.App()

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

@app.cell
def _(mo):
    mo.md("# My Notebook")
    return ()

API リファレンス

各 API の詳細なドキュメントは references/ ディレクトリにあります。包括的な例やパラメーターについては、これらのファイルを参照してください。

コア

API	リファレンスファイル	説明
Markdown	references/markdown.md	リッチテキスト、LaTeX、アイコンに対応する mo.md()
HTML	references/html.md	mo.Html、mo.as_html()、スタイリング
出力	references/outputs.md	mo.output.append()、コンソールのリダイレクト

UI 要素

API	リファレンスファイル	説明
入力	references/inputs.md	スライダー、テキスト、ドロップダウン、テーブル、フォームなど
レイアウト	references/layouts.md	mo.hstack、mo.vstack、タブ、アコーディオンなど
メディア	references/media.md	画像、音声、動画、PDF、ダウンロード
プロット	references/plotting.md	Altair、Plotly、matplotlib との連携
ダイアグラム	references/diagrams.md	Mermaid ダイアグラム
ステータス	references/status.md	プログレスバー、スピナー

データ

API	リファレンスファイル	説明
SQL	references/sql.md	データベースや DataFrame のクエリに使う mo.sql()

高度な機能

API	リファレンスファイル	説明
制御フロー	references/control-flow.md	mo.stop()、条件付き実行
状態	references/state.md	UI の同期に使う mo.state()
キャッシュ	references/caching.md	@mo.cache、@mo.persistent_cache
クエリパラメーター	references/query-params.md	URL の状態を扱う mo.query_params()
CLI 引数	references/cli-args.md	スクリプト引数を扱う mo.cli_args()
監視	references/watch.md	リアクティブなファイル監視に使う mo.watch.file()
アプリ	references/app.md	ノートブックの埋め込み、mo.app_meta()
セル	references/cell.md	ノートブック間の実行、テスト

クイック例

基本的な UI

import marimo as mo

slider = mo.ui.slider(0, 100, value=50, label="Threshold")
slider

# In another cell
mo.md(f"Selected value: **{slider.value}**")

インタラクティブなテーブル

table = mo.ui.table(df, selection="multi")
table

# In another cell
selected = table.value  # Selected rows as DataFrame

SQL クエリ

result = mo.sql(f"SELECT * FROM {df} WHERE value > {threshold.value}")

条件付き実行

mo.stop(form.value is None, mo.md("Submit the form to continue"))
# Rest of cell runs only after form submission

アプリとして実行

marimo run notebook.py                    # Local app
marimo export html-wasm notebook.py       # Static WASM app

レイアウトのオプション：垂直（デフォルト）、グリッド（エディターでドラッグ＆ドロップ）、スライド。

ベストプラクティス

• リアクティビティ：同じセル内で変数を宣言し、変更してください
• パフォーマンス：計算コストの高い処理には @mo.cache を使ってください
• UI の制御：準備が整うまでコストの高い処理を防ぐには、mo.stop() を使ってください
• 状態：複数の UI 要素を同期する場合を除き、mo.state() の使用は避けてください
• 整理：セルの位置は関係ありません。読みやすさを優先して整理してください

リソース

• ドキュメント
• GitHub
• サンプルギャラリー