Marimo notebook 使い方 – 次世代Pythonノートブック完全解説

序論：リアクティブなノートブック体験への革命

データサイエンスと機械学習の現場において、Jupyter Notebookは長年にわたってデファクトスタンダードの地位を築いてきました。しかし、隠れた状態の問題、バージョン管理の困難さ、そして手動でのセル実行管理といった根本的な課題が、研究者や開発者の生産性を阻害し続けています。

marimo（マリモ）は、これらの従来ノートブックの構造的欠陥を根本から解決するために設計された、オープンソースのリアクティブPythonノートブック環境です。本記事では、元Google BrainのAIリサーチャーとしての実践的知見を活かし、marimoの技術的アーキテクチャから実装手法、そして本格的な運用方法まで、網羅的に解説します。

第1章：marimoの技術的基盤と設計思想

1.1. リアクティブ実行エンジンの内部構造

marimoの中核をなすのは、セル間の依存関係を有向非循環グラフ（Directed Acyclic Graph, DAG）として構築する静的解析エンジンです。この仕組みは、従来のノートブックの線形実行モデルとは根本的に異なります。

DAGベースの実行制御

# marimoの内部では、以下のような依存関係解析が行われます
# セル1: x = 10
# セル2: y = x * 2  
# セル3: z = y + 5

# この場合、DAG構造は以下のようになります：
# セル1 → セル2 → セル3

marimoは各セルのコードを静的に解析し、グローバル変数の定義（definitions）と参照（references）を特定します。その後、セル間にエッジを持つDAGを構築し、あるセルが実行されると、そのセルが定義する変数を参照する全ての依存セルが自動的に実行されます。

数学的基盤：偏順序関係

DAGの到達可能性関係は偏順序関係≤として形式化できます。頂点uからvへの有向パスが存在する場合、u ≤ vと定義されます。marimoはこの数学的性質を活用し、トポロジカルソートによって実行順序を決定的に決定します。

1.2. ピュアPythonファイル形式の技術的利点

marimoノートブックは純粋なPythonファイル（.py）として保存され、JSONベースのJupyterノートブックとは異なり、標準的なPython開発ツールとの完全な互換性を実現しています。

ファイル構造の詳細解析

import marimo

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

@app.cell
def __():
    import numpy as np
    import pandas as pd
    return np, pd

@app.cell
def __(np):
    data = np.random.randn(1000)
    return data,

@app.cell
def __(data, pd):
    df = pd.DataFrame({'values': data})
    return df,

この形式により、以下の技術的優位性が実現されます：

特徴	marimoの実装	Jupyterとの比較
バージョン管理	diffが明確で可読性が高い	JSON形式でmerge時に競合が頻発
実行可能性	python notebook.pyで直接実行可能	別途変換処理が必要
静的解析	linter、formatter、型チェッカーがそのまま適用可能	特別なツール設定が必要
CI/CD統合	標準的なPythonワークフローに組み込み可能	専用の前処理ステップが必要

1.3. メモリ管理とガベージコレクション

marimoは内部的に全セル間で共有される「グローバル辞書」を管理し、DAGに基づいて実行順序を決定します。セルが無効化される際には、変数の削除とガベージコレクションが自動的に実行されます。

実験的なストリクトモード

# marimo設定ファイル（~/.marimo.toml）での設定

[runtime]

execution_type = “strict” # 実験的機能

ストリクトモードでは、セル固有の「グローバル」環境を作成し、セル間での変数の暗黙的な変更を防止します。これにより隠れた状態の蓄積を完全に回避できますが、変数コピーのオーバーヘッドが発生します。

第2章：環境構築とインストレーション戦略

2.1. 最適化されたインストール手順

marimoの本格的な活用には、基本インストールに加えて、SQL セル、AI補完、そしてサーバーサイドでのデータフレーム可視化などの高度な機能を有効化する必要があります。

プロダクション環境での推奨セットアップ

# 仮想環境の作成（本番環境推奨）
python -m venv marimo-env
source marimo-env/bin/activate  # Linux/macOS
# marimo-env\Scripts\activate  # Windows

# 推奨依存関係を含む完全インストール
pip install "marimo[recommended]"

# インストール確認
marimo tutorial intro

uvパッケージマネージャーとの連携

uvは次世代Python パッケージマネージャーで、pipの10-100倍高速です。プロジェクト管理の効率化に有効です：

# uvを使用した高速インストール
uv add "marimo[recommended]"
uv run marimo tutorial intro

2.2. 依存関係の詳細分析

marimo[recommended]インストールでは、以下の依存関係が追加されます：

依存パッケージ	機能	技術的意義
duckdb>=1.0.0	SQLセル	OLAP処理と高速分析クエリ
altair>=5.4.0	データソースビューアでの描画	宣言的可視化とインタラクティブ性
polars[pyarrow]>=1.9.0	SQLのPolarsサポート	高性能データフレーム処理
openai>=1.55.3	AI補完機能	GPTベースのコード生成支援
ruff	コードフォーマット	Rust製の高速リンター/フォーマッター

2.3. 高度な設定とカスタマイゼーション

GitHub Copilotの統合設定

marimoエディタは、VS Codeと同様にGitHub Copilotをネイティブサポートしています：

# Node.jsのインストール（Copilot要件）
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm

# marimo設定でCopilotを有効化
# エディタのSettings menu → Enable Copilot

重要な制約事項：CopilotはPyPI版でのみ利用可能で、conda配布版では現在サポートされていません。

第3章：marimoの実践的使用法

3.1. 基本的なセル操作とワークフロー

セル作成とリアクティブ実行

# セル1: データ生成
import marimo as mo
import numpy as np
import pandas as pd

# 基本データの作成
data = np.random.normal(100, 15, 1000)
df = pd.DataFrame({
    'values': data,
    'category': np.random.choice(['A', 'B', 'C'], 1000)
})

# セル2: データ処理（セル1に依存）
# data, dfがセル1で定義されているため、自動的に依存関係が構築される
summary_stats = df.groupby('category').agg({
    'values': ['mean', 'std', 'count']
}).round(2)

# 出力
summary_stats

インタラクティブUI要素の実装

marimoの最も強力な機能の一つは、グローバル変数に束縛されたUI要素とのインタラクションによる自動的なセル実行です：

# セル3: インタラクティブ制御
category_selector = mo.ui.dropdown(
    options=['All'] + list(df['category'].unique()),
    value='All',
    label='カテゴリ選択'
)

threshold_slider = mo.ui.range_slider(
    start=df['values'].min(),
    stop=df['values'].max(),
    value=[df['values'].quantile(0.25), df['values'].quantile(0.75)],
    label='値の範囲',
    step=1
)

mo.md(f"""
## データフィルタリング制御
カテゴリ: {category_selector}  
値の範囲: {threshold_slider}
""")

# セル4: フィルタリング処理（セル3のUI要素に依存）
filtered_df = df.copy()

# カテゴリフィルタリング
if category_selector.value != 'All':
    filtered_df = filtered_df[filtered_df['category'] == category_selector.value]

# 値の範囲フィルタリング  
min_val, max_val = threshold_slider.value
filtered_df = filtered_df[
    (filtered_df['values'] >= min_val) & 
    (filtered_df['values'] <= max_val)
]

mo.md(f"フィルタ後のレコード数: {len(filtered_df)}")

3.2. 高度なUI要素の活用

複合UI要素の構築

marimoは、mo.ui.arrayやmo.ui.dictionaryを使用して、実行時に決定される UI要素のコレクションを効率的に管理できます：

# 動的UI要素の生成
analysis_params = mo.ui.dictionary({
    'bins': mo.ui.slider(10, 100, value=30, label='ヒストグラムのビン数'),
    'alpha': mo.ui.slider(0.1, 1.0, value=0.7, step=0.1, label='透明度'),
    'color_palette': mo.ui.dropdown(['viridis', 'plasma', 'coolwarm'], value='viridis'),
    'show_kde': mo.ui.checkbox(True, label='カーネル密度推定を表示')
})

analysis_params

フォームベースの一括処理

# バッチ処理用フォーム
batch_config = mo.ui.form({
    'output_format': mo.ui.radio(['PNG', 'SVG', 'PDF'], value='PNG'),
    'resolution': mo.ui.number(300, label='DPI'),
    'include_statistics': mo.ui.checkbox(True),
    'export_data': mo.ui.checkbox(False)
})

batch_config

3.3. SQLセルの活用とデータベース統合

marimoはDuckDBと密接に統合されており、Python と SQL を単一のノートブック内でシームレスに混在させることができます。

DuckDBとの統合実装

# セル1: データベース接続設定
import duckdb
import marimo as mo

# カスタムDuckDB接続の作成
conn = duckdb.connect("analysis.db")

# セル2: SQLセルでのデータ操作
# mo.sql()を使用してSQLを実行
query_result = mo.sql(
    f"""
    SELECT 
        category,
        AVG(values) as avg_value,
        STDDEV(values) as std_value,
        COUNT(*) as count
    FROM df  -- Python変数を直接参照可能
    WHERE values BETWEEN {threshold_slider.value[0]} AND {threshold_slider.value[1]}
    GROUP BY category
    ORDER BY avg_value DESC
    """,
    output=True  # 結果をPython変数として利用可能
)

第4章：Jupyterからmarimoへの移行戦略

4.1. 自動変換ツールの活用

marimoは既存のJupyterノートブックを自動的にmarimoノートブックに変換するCLIツールを提供しています：

# Jupyterノートブックの変換
marimo convert analysis.ipynb -o analysis.py

# 変換後のノートブックを開く
marimo edit analysis.py

4.2. 移行時の主要な考慮事項

変数スコープの再設計

marimoでは同じ変数を複数のセルで定義することはできません。そうしなければ、marimoがセルの実行順序を決定できなくなります。

# Jupyterでの従来の手法（marimoでは不適切）
# セル1:
df = pd.read_csv('data.csv')

# セル2: 
df = df.dropna()  # 同じ変数名を再定義

# セル3:
df = df[df['value'] > 0]  # さらに再定義

# marimoに適合した設計パターン
# セル1: データ読み込み
raw_df = pd.read_csv('data.csv')

# セル2: データクリーニング  
cleaned_df = raw_df.dropna()

# セル3: フィルタリング
filtered_df = cleaned_df[cleaned_df['value'] > 0]

セル統合による効率化

# 推奨：関連する処理を単一セルに統合
def process_data(raw_data):
    """データ処理パイプライン"""
    return (raw_data
            .dropna()
            .query('value > 0')
            .reset_index(drop=True))

final_df = process_data(raw_df)

4.3. 実行順序の制御と依存関係管理

marimoでは、セルの実行順序はページ上の位置ではなく、変数の関係性によって完全に決定されます。これにより、論理的な構造と物理的な配置を分離できます。

# 依存関係の可視化
# marimoエディタで「Explore dependencies」ツールを使用
# 内部DAG構造を確認可能

第5章：プロダクション環境での高度な活用

5.1. Webアプリケーションとしてのデプロイメント

marimoノートブックは、本格的なWebアプリケーションとして展開でき、開発インターフェースを隠蔽した洗練されたユーザー体験を提供します。

基本的なWebアプリデプロイメント

# 読み取り専用Webアプリとして起動
marimo run dashboard.py --host 0.0.0.0 --port 8080

# サブパスでのデプロイメント
marimo run dashboard.py --base-url /analytics/

# ヘルスチェックエンドポイント
curl http://localhost:8080/health

Dockerコンテナでの本番デプロイメント

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# 依存関係のインストール
COPY requirements.txt .
RUN pip install -r requirements.txt

# marimoノートブックのコピー
COPY dashboard.py .

# ポート公開
EXPOSE 8080

# アプリケーション起動
CMD ["marimo", "run", "dashboard.py", "--host", "0.0.0.0", "--port", "8080"]

5.2. ASGI統合とFastAPI連携

marimoアプリをFastAPIなどの他のASGIアプリケーションに組み込むことで、より大規模なシステムの一部として運用できます：

# main.py
from fastapi import FastAPI
from marimo._runtime.app import App
import marimo

app = FastAPI()

# marimoアプリケーションの読み込み
marimo_app = marimo.create_asgi_app().with_app(
    path="/analytics", 
    root="dashboard.py"
)

# FastAPIにマウント
app.mount("/analytics", marimo_app)

@app.get("/")
async def root():
    return {"message": "Analytics Dashboard Available at /analytics"}

5.3. WebAssemblyによる配布戦略

marimoは、WebAssembly（WASM）を利用してPythonの実行環境を不要とする完全にフロントエンドで動作するアプリケーションとして配布可能です。

# WASM形式でのHTML出力
marimo export html-wasm analysis.py -o ./dist --mode edit

# 静的ホスティングサービスでの配布が可能
# - GitHub Pages
# - Netlify  
# - Vercel

WASM配布の制約事項

WebAssembly環境では、Pythonパッケージの一部が利用できない制約があります。主にWebAssembly向けにビルドされていないパッケージが対象となります。

第6章：高度なデータサイエンス活用事例

6.1. 機械学習パイプラインの構築

# セル1: ライブラリと設定
import marimo as mo
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report, confusion_matrix
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

# データ読み込み
data = pd.read_csv('dataset.csv')

# セル2: インタラクティブなパラメータ制御
ml_config = mo.ui.dictionary({
    'test_size': mo.ui.slider(0.1, 0.5, value=0.2, step=0.05, label='テストサイズ'),
    'n_estimators': mo.ui.slider(10, 200, value=100, step=10, label='決定木数'),
    'max_depth': mo.ui.slider(1, 20, value=10, label='最大深度'),
    'random_state': mo.ui.number(42, label='乱数シード')
})

ml_config

# セル3: モデル訓練（リアクティブに実行）
# 特徴量とターゲットの分離
X = data.drop('target', axis=1)
y = data['target']

# 訓練・テスト分割
X_train, X_test, y_train, y_test = train_test_split(
    X, y, 
    test_size=ml_config.value['test_size'],
    random_state=ml_config.value['random_state']
)

# モデル訓練
model = RandomForestClassifier(
    n_estimators=ml_config.value['n_estimators'],
    max_depth=ml_config.value['max_depth'],
    random_state=ml_config.value['random_state']
)

model.fit(X_train, y_train)
predictions = model.predict(X_test)

# 性能評価
accuracy = model.score(X_test, y_test)
mo.md(f"**モデル精度: {accuracy:.3f}**")

6.2. インタラクティブな可視化システム

marimoは、AltairとPlotlyチャートのインタラクティブ機能をネイティブサポートし、チャートでの選択操作が自動的にPythonコードに伝播されます：

# インタラクティブPlotlyチャート
import plotly.graph_objects as go
import plotly.express as px

# 散布図の作成（選択可能）
scatter_plot = px.scatter(
    data, 
    x='feature1', 
    y='feature2', 
    color='target',
    title='インタラクティブ散布図'
)

# Plotlyチャートの表示
scatter_plot

# 選択されたポイントに基づく詳細分析
# （Plotlyの選択機能と自動連携）
if hasattr(scatter_plot, 'selected_data') and scatter_plot.selected_data:
    selected_indices = scatter_plot.selected_data
    selected_data = data.iloc[selected_indices]
    
    mo.md(f"選択されたデータポイント数: {len(selected_data)}")
    mo.ui.table(selected_data)
else:
    mo.md("チャート上でポイントを選択してください")

6.3. リアルタイムデータ分析ダッシュボード

# セル1: データ更新制御
refresh_interval = mo.ui.slider(
    1, 60, value=5, 
    label='更新間隔（秒）'
)

auto_refresh = mo.ui.checkbox(
    True, 
    label='自動更新を有効化'
)

mo.md(f"""
## リアルタイムダッシュボード制御
{refresh_interval}  
{auto_refresh}
""")

# セル2: データ取得と前処理
import time
from datetime import datetime, timedelta

def fetch_realtime_data():
    """実際の環境では、API、データベース、ストリームから取得"""
    current_time = datetime.now()
    # シミュレーションデータ
    return pd.DataFrame({
        'timestamp': [current_time - timedelta(minutes=i) for i in range(100)],
        'value': np.random.normal(100, 15, 100),
        'category': np.random.choice(['A', 'B', 'C'], 100)
    })

# 条件付きデータ更新
if auto_refresh.value:
    live_data = fetch_realtime_data()
    mo.md(f"**最終更新: {datetime.now().strftime('%H:%M:%S')}**")
else:
    mo.md("自動更新が無効化されています")

第7章：パフォーマンス最適化と運用

7.1. 大規模データセットの処理

marimoは高コストなノートブックに対応するため、自動実行ではなく「stale」マーキングによる遅延実行モードを提供しています。

# 高コストなセルの実行制御
import marimo as mo

# 条件付き実行制御
expensive_computation_trigger = mo.ui.button(
    label="重い計算を実行",
    kind="success"
)

if expensive_computation_trigger.value:
    # 大規模データ処理
    large_dataset = pd.read_parquet('huge_dataset.parquet')
    result = complex_analysis(large_dataset)
    mo.md("✅ 計算完了")
else:
    mo.md("「重い計算を実行」ボタンをクリックしてください")

7.2. メモリ効率の最適化

メモリ使用量を最適化するため、不要になった大容量変数は明示的に削除することが推奨されます：

# メモリ効率的なデータ処理
def process_large_data():
    # 大容量データの読み込み
    huge_df = pd.read_parquet("massive_data.parquet")
    
    # 必要な部分のみ抽出
    partial_df = huge_df.filter(pl.col('important_column') > threshold)
    summary_stats = huge_df.group_by('category').agg(pl.count())
    
    # 大容量データを明示的に削除
    del huge_df
    
    return partial_df, summary_stats

# 処理実行
filtered_data, stats = process_large_data()

7.3. 実行時間の監視と最適化

# パフォーマンス監視
import time
from functools import wraps

def timing_decorator(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        mo.md(f"⏱️ {func.__name__}: {end-start:.2f}秒")
        return result
    return wrapper

@timing_decorator
def heavy_computation(data):
    # 時間のかかる処理
    return data.groupby('category').apply(lambda x: complex_operation(x))

# 使用例
result = heavy_computation(filtered_data)

第8章：限界とリスク、不適切なユースケース

8.1. 技術的制約事項

動的コード解析の限界

marimoは静的解析に依存するため、exec()、eval()、メタプログラミングなどの動的構造はアナライザーを混乱させる可能性があります。

# 問題のあるパターン（避けるべき）
variable_name = "dynamic_var"
exec(f"{variable_name} = 42")  # marimoは依存関係を検出できない

# 推奨される代替手法
dynamic_vars = {"dynamic_var": 42}
result = dynamic_vars["dynamic_var"]

エコシステムの成熟度

marimoのエコシステムは発展途上にあり、Jupyterの膨大なプラグインやツールチェーンとの互換性は限定的です。特に以下の制約があります：

制約カテゴリ	具体的な制限	回避策
既存ツール統合	JupyterHub、Binder、nbconvertとの直接統合不可	marimo独自のデプロイメント手法を使用
ファイル形式	.ipynbとの完全互換性なし	変換ツールを使用、手動調整が必要
UI コンポーネント	Jupyterと比較してUI要素が基本的	カスタムanywidgetの開発が必要

8.2. 不適切なユースケース

リニア実行が必須なワークフロー

# marimoに適さないパターン
# 時系列に依存する処理で、セルの実行順序が重要な場合
step1_result = initialize_model()
step2_result = train_model(step1_result)  # step1の完了が必要
step3_result = evaluate_model(step2_result)  # step2の完了が必要

大規模な既存Jupyterエコシステムとの統合

既存の組織で以下が重要な場合、marimoの導入は慎重に検討すべきです：

• JupyterHubベースの認証・権限管理システム
• Jupyter特化のCI/CDパイプライン
• nbextensionsに依存したワークフロー

8.3. セキュリティとコンプライアンス考慮事項

marimoアプリケーションを本番環境で運用する際は、適切な認証とセキュリティ設定が必要です：

# 本番環境でのセキュリティ設定例
# 環境変数での機密情報管理
import os
from marimo._runtime.app import App

app = App()

# 認証が必要な場合の実装
@app.cell
def __():
    api_key = os.getenv('API_KEY')
    if not api_key:
        raise ValueError("API_KEY environment variable is required")
    return api_key,

第9章：将来展望と発展方向性

9.1. AIネイティブ機能の拡張

marimoは、OpenAI互換モデル、Anthropic、Google Gemini、Ollamaモデルを直接サポートし、コンテキスト対応のチャット、インライン編集、AI支援機能を統合しています。

# AI機能の活用例
# セル内でのAI支援コード生成
ai_prompt = mo.ui.text_area(
    placeholder="実装したい機能を説明してください",
    label="AI コード生成プロンプト"
)

if ai_prompt.value:
    # AIによるコード生成（統合機能）
    mo.md(f"**プロンプト**: {ai_prompt.value}")
    # marimoエディタ内でAI生成コードが自動提案される

9.2. エンタープライズ向け機能の発展

marimoチームは商用版の提供と、AI統合の強化を計画しており、エンタープライズ環境での本格運用に向けた機能拡張が予想されます。

期待される発展方向：

• 企業向け認証システム: SAML、OIDC統合
• スケーラブルな実行環境: Kubernetes、クラウドネイティブサポート
• 高度なコラボレーション機能: リアルタイム共同編集、レビュー機能
• エンタープライズセキュリティ: 詳細な監査ログ、データガバナンス

9.3. リアクティブプログラミングパラダイムの普及

marimoは、IPyflow、Streamlit、TensorFlow、PyTorch、JAX、Reactなどのツールと共に、関数型、宣言型、リアクティブプログラミングの普及を牽引する重要な要素となっています。

この技術トレンドにより、以下の発展が期待されます：

• 統一されたデータフロープログラミング: 異なるツール間でのシームレスな統合
• イミュータブルデータ処理: 副作用のない安全なデータパイプライン
• 宣言的UI構築: より直感的で保守性の高いインタラクティブアプリケーション

結論：marimoがもたらすパラダイムシフト

marimoは単なるJupyterの代替品を超えて、計算ノートブックの概念そのものを再定義する技術的革新です。リアクティブ実行、純粋Pythonファイル形式、組み込みUI要素の三位一体により、研究から生産まで一貫したワークフローを実現します。

主要な技術的優位性

1. 決定論的実行: DAGベースの実行制御による完全な再現性
2. 開発者エクスペリエンス: 標準Pythonツールチェーンとの完全統合
3. インタラクティビティ: コールバック不要のリアクティブUI要素
4. デプロイメント柔軟性: スクリプト、Webアプリ、WASM配布の三形態対応

導入戦略と実践的推奨事項

• パイロットプロジェクト: 新規プロジェクトでの段階的導入
• チームトレーニング: リアクティブプログラミング概念の習得
• 技術スタック整備: CI/CD、デプロイメント環境の準備
• エコシステム監視: marimoコミュニティと技術動向の継続的追跡

marimoは、データサイエンティストと開発者が「使い捨てのノートブック」から「再利用可能なmarimoミニアプリライブラリ」へと移行できる環境を提供します。この技術的転換により、研究と実装、探索と展開の境界線が消失し、より効率的で持続可能な開発プロセスが実現されるでしょう。

marimoの真の価値は、個々の機能ではなく、リアクティブプログラミングパラダイムを通じた思考プロセスの変革にあります。計算ノートブックが単なるプロトタイピングツールから、本格的なソフトウェア開発プラットフォームへと進化する時代において、marimoは間違いなく先駆的な存在として位置づけられるのです。

---

参考文献

1. marimo公式ドキュメント
2. marimo GitHub リポジトリ
3. Real Python – marimo: A Reactive, Reproducible Notebook
4. DuckDB – marimo Notebooks
5. IBM – What Is a Directed Acyclic Graph (DAG)?
6. Data Engineering Podcast – Revolutionizing Python Notebooks with Marimo

本記事の技術情報は2025年7月時点のmarimoバージョンに基づいています。最新の機能や変更については、公式ドキュメントをご確認ください。