marimo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

VALIDATE syntax and structure:
```
marimo check notebook.py
```

EXECUTE with outputs:

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

VERIFY using notebook-debug skill's verification checklist
CLAIM success only after verification passes

This is not negotiable. Claiming "notebook works" without executing and inspecting outputs is LYING to the user.

在声称任何marimo笔记本可正常运行前：

验证语法与结构：
```
marimo check notebook.py
```

执行并生成输出：

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

核查使用notebook-debug技能的验证检查清单
仅在验证通过后声明运行成功

该规则不可妥协。未执行并核查输出就声称「笔记本可正常运行」属于对用户的欺骗。

Rationalization Table - STOP If You Think:

合理化对照表 - 如有以下想法请立刻停止：

Excuse	Reality	Do Instead
"marimo check passed, so it works"	Syntax check ≠ runtime correctness	EXECUTE with --include-outputs and inspect
"Just a small change, can't break anything"	Reactivity means small changes propagate everywhere	VERIFY with full execution
"I'll let marimo handle the dependency tracking"	Verification of correct behavior is still required	CHECK outputs match expectations
"The function signature looks right"	Wrong deps/returns break reactivity silently	VALIDATE all vars are in params AND returns
"I can modify the function signature"	Breaks marimo's dependency detection	ONLY edit inside function bodies
"Variables can be used without returning them"	Will cause NameError in dependent cells	RETURN 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命令

Command	Purpose
`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 to ipynb with outputs (runs notebook first)

marimo：导出ipynb包含输出（会先运行笔记本）

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 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

常见问题

Issue	Fix
Variable redefinition	Rename one variable or merge cells
Circular dependency	Break cycle by merging or restructuring
Missing return	Add `return var,` with trailing comma
Import not available	Ensure 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调用）

marimo

Original

Translation

Contents

目录

Marimo Reactive Notebooks

Marimo响应式笔记本

Editing and Verification Enforcement

编辑与验证强制规范

IRON LAW #1: NEVER MODIFY CELL DECORATORS OR SIGNATURES

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

IRON LAW #2: NO EXECUTION CLAIM WITHOUT OUTPUT VERIFICATION

铁律2：未验证输出不得声称执行成功

Rationalization Table - STOP If You Think:

合理化对照表 - 如有以下想法请立刻停止：

Red Flags - STOP Immediately If You Think:

危险信号 - 如有以下想法请立刻停止：

Editing Checklist

编辑检查清单

Gate Function: Marimo Verification

把关函数：Marimo验证

Honesty Framing

诚实准则

Key Concepts

核心概念

Cell Structure

单元格结构

Editing Rules

编辑规则

Core CLI Commands

核心CLI命令

Export Commands

导出命令

marimo: Export to ipynb with code only

marimo：仅导出代码到ipynb

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

marimo：导出ipynb包含输出（会先运行笔记本）

marimo: Export to HTML (runs notebook by default)

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

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

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

Data and Visualization

数据与可视化

Debugging Workflow

调试工作流

scripts: Validate notebook syntax and cell structure

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

marimo: Export to ipynb with outputs for inspection

marimo：导出包含输出的ipynb用于核查

Common Issues

常见问题

Additional Resources

额外资源

Reference Files

参考文件

Examples

示例

Scripts

脚本

Related Skills

相关技能