用途:用于创建和编辑 marimo notebook,处理任何含 @app.cell 装饰器的 .py 文件,构建响应式 Python notebook。
主要能力:
- 响应式模型:通过静态分析从变量引用与定义构建依赖图,单元格依赖变化即自动重跑,执行顺序依依赖图而非视觉顺序;每个全局变量只能由一个单元格定义。
- 不追踪对象原地修改(如 list.append),需在创建对象的同一单元格内修改或新建变量。
- 避免变量名冲突:优先把代码包进函数,或使用有意义且唯一的变量名;禁止用下划线前缀生成唯一变量名。
- 结构:import marimo、app = marimo.App(width="medium"),每个单元格为 @app.cell 装饰的函数,通过返回元组共享变量,通过参数接收变量。
常用命令:marimo new;marimo edit notebook.py(--watch 实时重载);marimo run notebook.py(默认隐藏代码,--include-code 显示);marimo convert notebook.ipynb -o notebook.py;marimo export html/ipynb;marimo check notebook.py(--fix 自动修复)。
界面与输出:mo.md() 支持 Markdown、变量插值、LaTeX、图标;mo.ui.* 提供 slider、number、text、checkbox、dropdown、radio、multiselect、button、run_button、table、dataframe、data_explorer、表单 batch;布局有 mo.hstack、mo.vstack、mo.accordion、mo.tabs、mo.callout、mo.sidebar、mo.tree、mo.stat、mo.lazy;输出有 mo.output.replace/append/clear;进度与状态用 mo.status.progress_bar、spinner;流程控制用 mo.stop();缓存用 @mo.cache、@mo.persistent_cache;状态用 mo.state(),但超过 99% 的场景不需要。
可交互绘图:Altair、Plotly、Matplotlib(mo.mpl.interactive)等;另支持 wigglystuff 组件如 Slider2D、Paint、SortableList、Matrix、CellTour。
限制与注意:run 模式默认隐藏代码,教程需用 mo.show_code() 并作为独立语句调用,不能放进 return;不要用 print(),改用 mo.md、mo.stat、mo.callout 或直接返回对象;编辑前先读取文件当前状态并运行 marimo check,编辑后替换所有 print 并再次 check。官方文档:https://docs.marimo.io