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技能的验证检查清单
  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`技能：
```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

相关技能

  • notebook-debug
     - Debugging executed ipynb files with tracebacks and output inspection
  • notebook-debug
     - 调试已执行的ipynb文件，排查回溯错误和输出问题