marimo-notebook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Notes for marimo Notebooks

marimo笔记本编写注意事项

Running Marimo Notebooks

运行marimo笔记本

bash

undefined

bash

undefined

Run as script (non-interactive, for testing)

以脚本模式运行（非交互式，用于测试）

uv run <notebook.py>

Run interactively in browser

在浏览器中交互式运行

uv run marimo run <notebook.py>

Edit interactively

交互式编辑

uv run marimo edit <notebook.py>

undefined

uv run marimo edit <notebook.py>

undefined

Script Mode Detection

脚本模式检测

Use

mo.app_meta().mode == "script"

to detect CLI vs interactive:

python

@app.cell
def _(mo):
    is_script_mode = mo.app_meta().mode == "script"
    return (is_script_mode,)

使用

mo.app_meta().mode == "script"

来检测是CLI模式还是交互式模式：

python

@app.cell
def _(mo):
    is_script_mode = mo.app_meta().mode == "script"
    return (is_script_mode,)

Key Principle: Keep It Simple

核心原则：保持简洁

Show all UI elements always. Only change the data source in script mode.

Sliders, buttons, widgets should always be created and displayed
In script mode, just use synthetic/default data instead of waiting for user input
Don't wrap everything in
```
if not is_script_mode
```
conditionals
Don't use try/except for normal control flow

始终显示所有UI元素。仅在脚本模式下更改数据源。

滑块、按钮、小部件应始终创建并显示
在脚本模式下，只需使用模拟/默认数据，无需等待用户输入
不要将所有内容都包裹在
```
if not is_script_mode
```
条件判断中
不要在常规控制流中使用try/except

Good Pattern

良好实践

python

undefined

python

undefined

Always show the widget

始终显示小部件

@app.cell def _(ScatterWidget, mo): scatter_widget = mo.ui.anywidget(ScatterWidget()) scatter_widget return (scatter_widget,)

Only change data source based on mode

仅根据模式更改数据源

@app.cell def _(is_script_mode, make_moons, scatter_widget, np, torch): if is_script_mode: # Use synthetic data for testing X, y = make_moons(n_samples=200, noise=0.2) X_data = torch.tensor(X, dtype=torch.float32) y_data = torch.tensor(y) data_error = None else: # Use widget data in interactive mode X, y = scatter_widget.widget.data_as_X_y # ... process data ... return X_data, y_data, data_error

@app.cell def _(is_script_mode, make_moons, scatter_widget, np, torch): if is_script_mode: # 使用模拟数据进行测试 X, y = make_moons(n_samples=200, noise=0.2) X_data = torch.tensor(X, dtype=torch.float32) y_data = torch.tensor(y) data_error = None else: # 在交互式模式下使用小部件数据 X, y = scatter_widget.widget.data_as_X_y # ... 处理数据 ... return X_data, y_data, data_error

Always show sliders - use their .value in both modes

始终显示滑块 - 在两种模式下都使用其.value属性

@app.cell def _(mo): lr_slider = mo.ui.slider(start=0.001, stop=0.1, value=0.01) lr_slider return (lr_slider,)

Auto-run in script mode, wait for button in interactive

脚本模式下自动运行，交互式模式下等待按钮点击

@app.cell def _(is_script_mode, train_button, lr_slider, run_training, X_data, y_data): if is_script_mode: # Auto-run with slider defaults results = run_training(X_data, y_data, lr=lr_slider.value) else: # Wait for button click if train_button.value: results = run_training(X_data, y_data, lr=lr_slider.value) return (results,)

undefined

@app.cell def _(is_script_mode, train_button, lr_slider, run_training, X_data, y_data): if is_script_mode: # 使用滑块默认值自动运行 results = run_training(X_data, y_data, lr=lr_slider.value) else: # 等待按钮点击 if train_button.value: results = run_training(X_data, y_data, lr=lr_slider.value) return (results,)

undefined

Don't Guard Cells with

if

Statements

不要用

if

语句包裹单元格

Marimo's reactivity means cells only run when their dependencies are ready. Don't add unnecessary guards:

python

undefined

Marimo的响应式特性意味着单元格仅在其依赖项就绪时才会运行。不要添加不必要的判断：

python

undefined

BAD - the if statement prevents the chart from showing

错误写法 - if语句会阻止图表显示

@app.cell def _(plt, training_results): if training_results: # WRONG - don't do this fig, ax = plt.subplots() ax.plot(training_results['losses']) fig return

@app.cell def _(plt, training_results): if training_results: # 错误 - 不要这样做 fig, ax = plt.subplots() ax.plot(training_results['losses']) fig return

GOOD - let marimo handle the dependency

正确写法 - 让marimo处理依赖关系

@app.cell def _(plt, training_results): fig, ax = plt.subplots() ax.plot(training_results['losses']) fig return


The cell won't run until `training_results` has a value anyway.

@app.cell def _(plt, training_results): fig, ax = plt.subplots() ax.plot(training_results['losses']) fig return


在`training_results`有值之前，单元格不会运行。

Don't Use try/except for Control Flow

不要在控制流中使用try/except

Don't wrap code in try/except blocks unless you're handling a specific, expected exception. Let errors surface naturally.

python

undefined

除非你要处理特定的、可预期的异常，否则不要将代码包裹在try/except块中。让错误自然暴露。

python

undefined

BAD - hiding errors behind try/except

错误写法 - 用try/except隐藏错误

@app.cell def _(scatter_widget, np, torch): try: X, y = scatter_widget.widget.data_as_X_y X = np.array(X, dtype=np.float32) # ... except Exception as e: return None, None, f"Error: {e}"

GOOD - let it fail if something is wrong

正确写法 - 如果出现问题就让它报错

@app.cell def _(scatter_widget, np, torch): X, y = scatter_widget.widget.data_as_X_y X = np.array(X, dtype=np.float32) # ...


Only use try/except when:
- You're handling a specific, known exception type
- The exception is expected in normal operation (e.g., file not found)
- You have a meaningful recovery action

@app.cell def _(scatter_widget, np, torch): X, y = scatter_widget.widget.data_as_X_y X = np.array(X, dtype=np.float32) # ...


仅在以下情况使用try/except：
- 你要处理特定的、已知的异常类型
- 该异常在正常操作中是可预期的（例如，文件未找到）
- 你有有意义的恢复措施

Cell Output Rendering

单元格输出渲染

Marimo only renders the final expression of a cell. Indented or conditional expressions won't render:

python

undefined

Marimo仅渲染单元格的最终表达式。缩进或条件中的表达式不会被渲染：

python

undefined

BAD - indented expression won't render

错误写法 - 缩进的表达式不会被渲染

@app.cell def _(mo, condition): if condition: mo.md("This won't show!") # WRONG - indented return

@app.cell def _(mo, condition): if condition: mo.md("这不会显示！") # 错误 - 缩进了 return

GOOD - final expression renders

正确写法 - 最终表达式会被渲染

@app.cell def _(mo, condition): result = mo.md("Shown!") if condition else mo.md("Also shown!") result # This renders because it's the final expression return

undefined

@app.cell def _(mo, condition): result = mo.md("显示内容！") if condition else mo.md("也会显示！") result # 这会被渲染，因为它是最终表达式 return

undefined

Marimo Variable Naming

Marimo变量命名

Variables in

for

loops that would conflict across cells need underscore prefix:

python

undefined

在

for

循环中，可能会跨单元格冲突的变量需要以下划线前缀：

python

undefined

Use _name, _model to make them cell-private

使用_name, _model使其成为单元格私有变量

for _name, _model in items: ...

undefined

for _name, _model in items: ...

undefined

PEP 723 Dependencies

PEP 723 依赖声明

python

undefined

python

undefined

/// script

requires-python = ">=3.12"

dependencies = [

"marimo",

"torch>=2.0.0",

]

///

undefined

undefined

Prefer pathlib over os.path

优先使用pathlib而非os.path

Use

pathlib.Path

for file path operations instead of

os.path

python

undefined

使用

pathlib.Path

进行文件路径操作，而非

os.path

：

python

undefined

GOOD - use pathlib

正确写法 - 使用pathlib

from pathlib import Path data_dir = Path(tempfile.mkdtemp()) parquet_file = data_dir / "data.parquet"

BAD - avoid os.path

错误写法 - 避免使用os.path

import os parquet_file = os.path.join(temp_dir, "data.parquet")

undefined

import os parquet_file = os.path.join(temp_dir, "data.parquet")

undefined

marimo check

marimo check命令

When working on a notebook it is important to check if the notebook can run. That's why marimo provides a

check

command that acts as a linter to find common mistakes.

bash

uvx marimo check <notebook.py>

Make sure these are checked before handing a notebook back to the user.

在开发笔记本时，检查笔记本是否能正常运行非常重要。marimo提供了

check

命令，作为代码检查工具来发现常见错误。

bash

uvx marimo check <notebook.py>

在将笔记本交付给用户之前，务必执行这些检查。

marimo-notebook

Original

Translation

Notes for marimo Notebooks

marimo笔记本编写注意事项

Running Marimo Notebooks

运行marimo笔记本

Run as script (non-interactive, for testing)

以脚本模式运行（非交互式，用于测试）

Run interactively in browser

在浏览器中交互式运行

Edit interactively

交互式编辑

Script Mode Detection

脚本模式检测

Key Principle: Keep It Simple

核心原则：保持简洁

Good Pattern

良好实践

Always show the widget

始终显示小部件

Only change data source based on mode

仅根据模式更改数据源

Always show sliders - use their .value in both modes

始终显示滑块 - 在两种模式下都使用其.value属性

Auto-run in script mode, wait for button in interactive

脚本模式下自动运行，交互式模式下等待按钮点击

Don't Guard Cells with if Statements

不要用if语句包裹单元格

BAD - the if statement prevents the chart from showing

错误写法 - if语句会阻止图表显示

GOOD - let marimo handle the dependency

正确写法 - 让marimo处理依赖关系

Don't Use try/except for Control Flow

不要在控制流中使用try/except

BAD - hiding errors behind try/except

错误写法 - 用try/except隐藏错误

GOOD - let it fail if something is wrong

正确写法 - 如果出现问题就让它报错

Cell Output Rendering

单元格输出渲染

BAD - indented expression won't render

错误写法 - 缩进的表达式不会被渲染

GOOD - final expression renders

正确写法 - 最终表达式会被渲染

Marimo Variable Naming

Marimo变量命名

Use _name, _model to make them cell-private

使用_name, _model使其成为单元格私有变量

PEP 723 Dependencies

PEP 723 依赖声明

/// script

/// script

requires-python = ">=3.12"

requires-python = ">=3.12"

dependencies = [

dependencies = [

"marimo",

"marimo",

"torch>=2.0.0",

"torch>=2.0.0",

]

]

///

///

Prefer pathlib over os.path

优先使用pathlib而非os.path

GOOD - use pathlib

正确写法 - 使用pathlib

BAD - avoid os.path

错误写法 - 避免使用os.path

marimo check

marimo check命令

Don't Guard Cells with
`if`
Statements

不要用
`if`
语句包裹单元格