Back to Details

marimo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Contents

目录

Marimo Reactive Notebooks

Marimo响应式笔记本

Marimo is a reactive Python notebook where cells form a DAG and auto-execute on dependency changes. Notebooks are stored as pure 
.py
files.
Marimo是一款响应式Python笔记本，其中单元格构成有向无环图（DAG），并会在依赖项变化时自动执行。笔记本以纯
.py
文件形式存储。

Editing and Verification Enforcement

编辑与验证铁律

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

铁律1：绝不修改单元格装饰器或签名

Only edit code INSIDE 
@app.cell
function bodies. This is not negotiable.
NEVER modify:
  • Cell decorators (
    @app.cell
    )
  • Function signatures (
    def _(deps):
    )
  • Return statements structure (trailing commas required)
ALWAYS verify:
  • All used variables are in function parameters
  • All created variables are in return statement
  • Trailing comma for single returns: 
    return var,
仅可编辑
@app.cell
函数体内的代码，这一点没有商量余地。
绝不修改：
  • 单元格装饰器（
    @app.cell
    ）
  • 函数签名（
    def _(deps):
    ）
  • 返回语句结构（必须保留末尾逗号）
必须验证：
  • 所有使用的变量均在函数参数中
  • 所有创建的变量均在返回语句中
  • 单个返回值需添加末尾逗号：
    return var,

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

铁律2：未验证输出绝不能宣称可执行

Before claiming ANY marimo notebook works:
  1. VALIDATE syntax and structure: 
    marimo check notebook.py
  2. EXECUTE with outputs: 
    marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
  3. VERIFY using notebook-debug skill's verification checklist
  4. CLAIM success only after verification passes
This is not negotiable. Claiming "notebook works" without executing and inspecting outputs is LYING to the user.
在宣称任何marimo笔记本可正常运行前：
  1. 验证语法与结构：
    marimo check notebook.py
  2. 执行并生成输出：
    marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
  3. 核查使用notebook-debug Skill的验证清单
  4. 仅在验证通过后，才可宣称运行正常
这一点没有商量余地。未执行且未检查输出就宣称“笔记本可运行”是对用户的欺骗。

Rationalization Table - STOP If You Think:

自我修正表——若你有以下想法，请立即停止：

ExcuseRealityDo Instead
"marimo check passed, so it works"Syntax check ≠ runtime correctnessEXECUTE with --include-outputs and inspect
"Just a small change, can't break anything"Reactivity means small changes propagate everywhereVERIFY with full execution
"I'll let marimo handle the dependency tracking"Verification of correct behavior is still requiredCHECK outputs match expectations
"The function signature looks right"Wrong deps/returns break reactivity silentlyVALIDATE all vars are in params AND returns
"I can modify the function signature"Breaks marimo's dependency detectionONLY edit inside function bodies
"Variables can be used without returning them"Will cause NameError in dependent cellsRETURN all created variables
"I can skip the trailing comma for single returns"Python treats 
return var
as returning the value, breaks unpacking		USE 
return var,
for single returns
借口实际情况正确做法
“marimo check通过了，所以没问题”语法检查≠运行时正确性执行
--include-outputs
命令并检查输出
“只是小改动，不会出问题”响应式特性意味着小改动会影响所有关联部分通过完整执行进行验证
“让marimo来处理依赖追踪”仍需验证行为是否正确检查输出是否符合预期
“函数签名看起来没问题”依赖项/返回值错误会静默破坏响应式特性验证所有变量均在参数和返回值中
“我可以修改函数签名”会破坏marimo的依赖检测机制仅编辑函数体内的代码
“变量可以不返回直接使用”会导致依赖单元格出现NameError错误返回所有创建的变量
“单个返回值可以省略末尾逗号”Python会将
return var
视为返回单个值，破坏解包逻辑		单个返回值需使用
return var,

Red Flags - STOP Immediately If You Think:

危险信号——若你有以下想法，请立即停止：

  • "Let me add this variable to the function signature" → NO. Marimo manages signatures.
  • "I'll just run marimo check and call it done" → NO. Execute with outputs required.
  • "The code looks correct" → NO. Marimo's reactivity must be verified at runtime.
  • "I can redefine this variable in another cell" → NO. One variable = one cell.
  • “我把这个变量加到函数签名里吧” → 不行，marimo会管理签名。
  • “我只运行marimo check就完事了” → 不行，必须执行并生成输出。
  • “代码看起来是对的” → 不行，必须在运行时验证marimo的响应式特性。
  • “我可以在另一个单元格里重新定义这个变量” → 不行，一个变量只能对应一个单元格。

Editing Checklist

编辑检查清单

Before every marimo edit:
Structure Validation:
  • Only edit code INSIDE 
    @app.cell
    function bodies
  • Do NOT modify decorators or signatures
  • Verify all used variables are in function parameters
  • Verify all created variables are in return statement
  • Ensure trailing comma used for single returns
  • Ensure no variable redefinitions across cells
Syntax Validation:
  • Execute 
    marimo check notebook.py
  • Verify no syntax errors reported
  • Verify no undefined variable warnings
  • Verify no redefinition warnings
Runtime Verification:
  • Execute with 
    marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
  • Verify export succeeded (exit code 0)
  • Verify output ipynb exists and is non-empty
  • Apply notebook-debug verification checklist
  • Verify no tracebacks in any cell
  • Verify all cells executed (execution_count not null)
  • Verify outputs match expectations
Only after ALL checks pass:
  • Claim "notebook works"
每次编辑marimo笔记本前：
结构验证：
  • 仅编辑
    @app.cell
    函数体内的代码
  • 绝不修改装饰器或签名
  • 验证所有使用的变量均在函数参数中
  • 验证所有创建的变量均在返回语句中
  • 确保单个返回值使用末尾逗号
  • 确保跨单元格无变量重定义
语法验证：
  • 执行
    marimo check notebook.py
  • 验证无语法错误报告
  • 验证无未定义变量警告
  • 验证无重定义警告
运行时验证：
  • 执行
    marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
  • 验证导出成功（退出码为0）
  • 验证输出的ipynb文件存在且非空
  • 应用notebook-debug验证清单
  • 验证所有单元格无回溯错误
  • 验证所有单元格已执行（execution_count不为空）
  • 验证输出符合预期
仅在所有检查通过后：
  • 宣称“笔记本可运行”

Gate Function: Marimo Verification

验证流程：Marimo验证

Follow this sequence for EVERY marimo task:
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
NEVER skip verification gates. Marimo's reactivity means changes propagate unpredictably.
所有marimo任务均需遵循以下流程：
1. 编辑     → 仅修改@app.cell函数体内的代码
2. 检查    → 执行marimo check notebook.py
3. 执行  → 执行marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
4. 核查  → 使用notebook-debug进行验证
5. 验证   → 输出符合预期
6. 宣称    → 仅在所有环节通过后，才可说“笔记本可运行”
绝不能跳过验证环节。marimo的响应式特性意味着改动会产生不可预测的传播。

Honesty Framing

诚信原则

Claiming a marimo notebook works without executing it with --include-outputs and inspecting the results is LYING.
Syntax checks and code inspection prove nothing about reactive execution correctness. The user expects a working notebook where all cells execute correctly with proper dependency tracking.
未执行
--include-outputs
命令且未检查结果就宣称marimo笔记本可运行，属于欺骗行为。
语法检查和代码检查无法证明响应式执行的正确性。用户期望的是一个可正常运行的笔记本，所有单元格均可正确执行且依赖追踪正常。

Key Concepts

核心概念

  • Reactive execution: Cells auto-update when dependencies change
  • No hidden state: Each variable defined in exactly one cell
  • Pure Python: 
    .py
    files, version control friendly
  • Cell structure: 
    @app.cell
    decorator pattern
  • 响应式执行：当依赖项变化时，单元格自动更新
  • 无隐藏状态：每个变量仅在一个单元格中定义
  • 纯Python：以
    .py
    文件存储，便于版本控制
  • 单元格结构：
    @app.cell
    装饰器模式

Cell Structure

单元格结构

python
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
python
import marimo

app = marimo.App()

@app.cell
def _(pl):  # 依赖项作为参数
    df = pl.read_csv("data.csv")
    return df,  # 单个返回值需保留末尾逗号

@app.cell
def _(df, pl):
    summary = df.describe()
    filtered = df.filter(pl.col("value") > 0)
    return summary, filtered  # 多个返回值

Editing Rules

编辑规则

  • Edit code INSIDE 
    @app.cell
    functions only
  • Never modify cell decorators or function signatures
  • Variables cannot be redefined across cells
  • All used variables must be returned from their defining cell
  • Markdown cells: Always wrap 
    $
    in backticks     - 
    mo.md("Cost:
    $50
    ")
    not 
    mo.md("Cost: $50")
  • 仅可编辑
    @app.cell
    函数体内的代码
  • 绝不修改单元格装饰器或函数签名
  • 不可跨单元格重定义变量
  • 所有使用的变量必须从其定义的单元格返回
  • Markdown单元格：始终用反引号包裹
    $
     - 使用
    mo.md("Cost:
    $50
    ")
    而非
    mo.md("Cost: $50")

Core CLI Commands

核心CLI命令

CommandPurpose
marimo edit notebook.py
marimo: Open notebook in browser editor for interactive development
marimo run notebook.py
marimo: Run notebook as executable app
marimo check notebook.py
marimo: Validate notebook structure and syntax without execution
marimo convert notebook.ipynb
marimo: Convert Jupyter notebook to marimo format
命令用途
marimo edit notebook.py
marimo：在浏览器编辑器中打开笔记本，进行交互式开发
marimo run notebook.py
marimo：将笔记本作为可执行应用运行
marimo check notebook.py
marimo：无需执行即可验证笔记本结构与语法
marimo convert notebook.ipynb
marimo：将Jupyter笔记本转换为marimo格式

Export Commands

导出命令

bash
undefined
bash
undefined

marimo: Export to ipynb with code only

marimo：仅导出代码到ipynb

marimo export ipynb notebook.py -o marimo/notebook.ipynb
marimo export ipynb notebook.py -o marimo/notebook.ipynb

marimo: Export to ipynb with outputs (runs notebook first)

marimo：导出带输出的ipynb（先运行笔记本）

marimo export ipynb notebook.py -o marimo/notebook.ipynb --include-outputs
marimo export ipynb notebook.py -o marimo/notebook.ipynb --include-outputs

marimo: Export to HTML (runs notebook by default)

marimo：导出为HTML（默认会运行笔记本）

marimo export html notebook.py -o marimo/notebook.html
marimo export html notebook.py -o marimo/notebook.html

marimo: Export to HTML with auto-refresh on changes (live preview)

marimo：导出为HTML并在改动时自动刷新（实时预览）

marimo export html notebook.py -o marimo/notebook.html --watch

**Key difference:** HTML export runs the notebook by default. ipynb export does NOT - use `--include-outputs` to run and capture outputs.

**Tip:** Use `__marimo__/` folder for all exports (ipynb, html). The editor can auto-save there.
marimo export html notebook.py -o marimo/notebook.html --watch

**关键区别**：HTML导出默认会运行笔记本，而ipynb导出不会——需使用`--include-outputs`参数来运行并捕获输出。

**提示**：所有导出文件（ipynb、html）均使用`__marimo__/`文件夹，编辑器可自动保存到该目录。

Data and Visualization

数据与可视化

  • Prefer polars over pandas for performance
  • Use 
    mo.ui
    for interactive widgets
  • SQL cells: 
    mo.sql(df, "SELECT * FROM df")
  • Display markdown: 
    mo.md("# Heading")
  • 为提升性能，优先使用polars而非pandas
  • 使用
    mo.ui
    创建交互式组件
  • SQL单元格：
    mo.sql(df, "SELECT * FROM df")
  • 显示Markdown：
    mo.md("# 标题")

Debugging Workflow

调试流程

1. Pre-execution validation:
bash
undefined
1. 执行前验证：
bash
undefined

scripts: Validate notebook syntax and cell structure

scripts：验证笔记本语法与单元格结构

scripts/check_notebook.sh notebook.py
Runs syntax check, marimo validation, and cell structure overview in one command.

**2. Runtime errors:** Export with outputs, then use `notebook-debug` skill:
```bash
scripts/check_notebook.sh notebook.py
该命令可一次性执行语法检查、marimo验证与单元格结构概览。

**2. 运行时错误：** 导出带输出的文件，然后使用`notebook-debug` Skill：
```bash

marimo: Export to ipynb with outputs for inspection

marimo：导出带输出的ipynb以便检查

marimo export ipynb notebook.py -o marimo/notebook.ipynb --include-outputs
undefined
marimo export ipynb notebook.py -o marimo/notebook.ipynb --include-outputs
undefined

Common Issues

常见问题

IssueFix
Variable redefinitionRename one variable or merge cells
Circular dependencyBreak cycle by merging or restructuring
Missing returnAdd 
return var,
with trailing comma
Import not availableEnsure import cell returns the module
问题解决方法
变量重定义重命名其中一个变量或合并单元格
循环依赖通过合并或重构打破循环
缺少返回值添加带末尾逗号的
return var,
导入不可用确保导入单元格返回了对应的模块

Additional Resources

额外资源

Reference Files

参考文档

For detailed patterns and advanced techniques, consult:
  • references/reactivity.md
     - DAG execution, variable rules, dependency detection patterns
  • references/debugging.md
     - Error patterns, runtime debugging, environment-specific issues
  • references/widgets.md
     - Interactive UI components and mo.ui patterns
  • references/sql.md
     - SQL cells and database integration techniques
如需了解详细模式与高级技巧，请查阅：
  • references/reactivity.md
     - DAG执行、变量规则、依赖检测模式
  • references/debugging.md
     - 错误模式、运行时调试、环境特定问题
  • references/widgets.md
     - 交互式UI组件与mo.ui模式
  • references/sql.md
     - SQL单元格与数据库集成技巧

Examples

示例

Working examples available in 
examples/
:
  • examples/basic_notebook.py
     - Minimal marimo notebook structure
  • examples/data_analysis.py
     - Data loading, filtering, and visualization patterns
  • examples/interactive_widgets.py
     - Interactive UI component usage
可在
examples/
目录下找到可用示例：
  • examples/basic_notebook.py
     - 最简marimo笔记本结构
  • examples/data_analysis.py
     - 数据加载、过滤与可视化模式
  • examples/interactive_widgets.py
     - 交互式UI组件使用示例

Scripts

脚本

Validation utilities in 
scripts/
:
  • scripts/check_notebook.sh
     - Primary validation: syntax check, marimo validation, cell structure overview
  • scripts/get_cell_map.py
     - Extract cell metadata (invoked by check_notebook.sh)
scripts/
目录下提供验证工具：
  • scripts/check_notebook.sh
     - 核心验证工具：语法检查、marimo验证、单元格结构概览
  • scripts/get_cell_map.py
     - 提取单元格元数据（由check_notebook.sh调用）

Related Skills

相关Skill

  • notebook-debug
     - Debugging executed ipynb files with tracebacks and output inspection
  • notebook-debug
     - 调试已执行的ipynb文件，包括回溯与输出检查