marimo

marimo

概述

marimo 是一款开源的响应式 Python 笔记本，将笔记本重新构想为可复现、可交互、可分享的 Python 程序。与传统的 Jupyter 笔记本不同，marimo 笔记本：

• 保存为纯 .py 文件（适合 Git，无 JSON）
• 以响应式方式运行（类似电子表格）
• 可作为脚本运行或部署为 Web 应用
• 通过自动依赖跟踪来预防错误

安装

pip install marimo                    # Basic
pip install marimo[recommended]       # With extras
pip install marimo[sql]               # With SQL support

marimo tutorial intro                 # Start tutorial

CLI 命令

# Edit
marimo edit                           # New notebook
marimo edit notebook.py               # Edit existing
marimo edit --watch --sandbox         # Watch files, isolate deps

# Run as app
marimo run notebook.py                # Read-only app
marimo run notebook.py --watch        # Auto-reload on changes

# Run as script
python notebook.py

# Create from prompt
marimo new "analyze sales data"

# Convert
marimo convert notebook.ipynb -o notebook.py

# Export
marimo export html notebook.py -o output.html
marimo export html-wasm notebook.py -o output.html  # Browser-executable

核心概念

响应性

运行一个单元格时，会自动运行所有依赖于它的单元格。执行顺序由变量依赖关系（DAG）决定，而不是由单元格的位置决定。

单元格规则

1. 每个全局变量都必须且只能在一个单元格中定义
2. list.append() 等修改操作不会被跟踪；请改为重新赋值
3. 如果需要进行修改，请在声明变量的同一单元格中操作

文件格式

笔记本是带有 marimo 装饰器的纯 Python 文件：

import marimo
app = marimo.App()

@app.cell
def _():
    import marimo as mo
    return (mo,)

@app.cell
def _(mo):
    mo.md("# My Notebook")
    return ()

API 参考

每个 API 的详细文档都在 references/ 目录中。请查阅这些文件，获取完整示例和参数说明。

核心

API	参考文件	说明
Markdown	references/markdown.md	mo.md()，用于富文本、LaTeX、图标
HTML	references/html.md	mo.Html、mo.as_html()、样式设置
输出	references/outputs.md	mo.output.append()、控制台重定向

UI 元素

API	参考文件	说明
输入	references/inputs.md	滑块、文本、下拉菜单、表格、表单等
布局	references/layouts.md	mo.hstack、mo.vstack、选项卡、折叠面板等
媒体	references/media.md	图像、音频、视频、PDF、下载
绘图	references/plotting.md	Altair、Plotly、matplotlib 集成
图表	references/diagrams.md	Mermaid 图表
状态	references/status.md	进度条、加载动画

数据

API	参考文件	说明
SQL	references/sql.md	mo.sql()，用于数据库和 DataFrame 查询

高级

API	参考文件	说明
控制流	references/control-flow.md	mo.stop()、条件执行
状态	references/state.md	mo.state()，用于 UI 同步
缓存	references/caching.md	@mo.cache、@mo.persistent_cache
查询参数	references/query-params.md	mo.query_params()，用于 URL 状态
CLI 参数	references/cli-args.md	mo.cli_args()，用于脚本参数
监视	references/watch.md	mo.watch.file()，用于响应式文件监视
应用	references/app.md	嵌入笔记本、mo.app_meta()
单元格	references/cell.md	跨笔记本执行、测试

快速示例

基本 UI

import marimo as mo

slider = mo.ui.slider(0, 100, value=50, label="Threshold")
slider

# In another cell
mo.md(f"Selected value: **{slider.value}**")

交互式表格

table = mo.ui.table(df, selection="multi")
table

# In another cell
selected = table.value  # Selected rows as DataFrame

SQL 查询

result = mo.sql(f"SELECT * FROM {df} WHERE value > {threshold.value}")

条件执行

mo.stop(form.value is None, mo.md("Submit the form to continue"))
# Rest of cell runs only after form submission

作为应用运行

marimo run notebook.py                    # Local app
marimo export html-wasm notebook.py       # Static WASM app

布局选项：垂直（默认）、网格（在编辑器中拖放）、幻灯片。

最佳实践

• 响应性：在同一单元格中声明和修改变量
• 性能：对开销较大的计算使用 @mo.cache
• UI 门控：使用 mo.stop()，在就绪前阻止开销较大的操作
• 状态：除非要同步多个 UI 元素，否则避免使用 mo.state()
• 组织：单元格位置无关紧要；请按可读性进行组织

资源

• 文档
• GitHub
• 示例集