Back to Details

marimo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

marimo

marimo

Overview

概述

marimo is an open-source reactive Python notebook that reinvents notebooks as reproducible, interactive, and shareable Python programs. Unlike traditional Jupyter notebooks, marimo notebooks:
  • Store as pure 
    .py
    files (Git-friendly, no JSON)
  • Execute reactively (like a spreadsheet)
  • Run as scripts or deploy as web apps
  • Prevent bugs through automatic dependency tracking
marimo是一款开源的响应式Python笔记本，它将笔记本重新定义为可复现、交互式且可共享的Python程序。与传统Jupyter笔记本不同，marimo笔记本具备以下特性：
  • 以纯
    .py
    文件格式存储（对Git友好，无JSON冗余）
  • 响应式执行（类似电子表格）
  • 可作为脚本运行或部署为Web应用
  • 通过自动依赖追踪避免错误

Installation

安装

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

marimo tutorial intro                 # Start tutorial
bash
pip install marimo                    # 基础版
pip install marimo[recommended]       # 含扩展功能
pip install marimo[sql]               # 含SQL支持

marimo tutorial intro                 # 启动教程

CLI Commands

CLI命令

bash
undefined
bash
undefined

Edit

编辑

marimo edit # New notebook marimo edit notebook.py # Edit existing marimo edit --watch --sandbox # Watch files, isolate deps
marimo edit # 创建新笔记本 marimo edit notebook.py # 编辑现有笔记本 marimo edit --watch --sandbox # 监听文件变化，隔离依赖

Run as app

作为应用运行

marimo run notebook.py # Read-only app marimo run notebook.py --watch # Auto-reload on changes
marimo run notebook.py # 只读模式运行应用 marimo run notebook.py --watch # 文件变化时自动重载

Run as script

作为脚本运行

python notebook.py
python notebook.py

Create from prompt

根据提示创建

marimo new "analyze sales data"
marimo new "analyze sales data"

Convert

格式转换

marimo convert notebook.ipynb -o notebook.py
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
undefined
marimo export html notebook.py -o output.html marimo export html-wasm notebook.py -o output.html # 可在浏览器中执行的版本
undefined

Key Concepts

核心概念

Reactivity

响应式

Running a cell automatically runs all cells that depend on it. Execution order is determined by variable dependencies (DAG), not cell position.
运行一个单元格时，会自动运行所有依赖于它的单元格。执行顺序由变量依赖关系（DAG）决定，而非单元格位置。

Cell Rules

单元格规则

  1. Each global variable must be defined in exactly one cell
  2. Mutations like 
    list.append()
    aren't tracked; reassign instead
  3. If mutating is needed, do it in the same cell as the declaration
  1. 每个全局变量必须在恰好一个单元格中定义
  2. 类似
    list.append()
    的突变操作不会被追踪；请改用重新赋值
  3. 若必须进行突变操作，请在变量声明的同一单元格中完成

File Format

文件格式

Notebooks are pure Python files with marimo decorators:
python
import marimo
app = marimo.App()

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

@app.cell
def _(mo):
    mo.md("# My Notebook")
    return ()
笔记本是带有marimo装饰器的纯Python文件：
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 Reference

API参考

Detailed documentation for each API is available in the 
references/
directory. Consult these files for comprehensive examples and parameters.
各API的详细文档可在
references/
目录中查看。如需全面的示例和参数说明，请查阅这些文件。

Core

核心

APIReference FileDescription
Markdown
references/markdown.md
mo.md()
for rich text, LaTeX, icons
HTML
references/html.md
mo.Html
, 
mo.as_html()
, styling
Outputs
references/outputs.md
mo.output.append()
, console redirection
API参考文档描述
Markdown
references/markdown.md
mo.md()
用于富文本、LaTeX、图标展示
HTML
references/html.md
mo.Html
、
mo.as_html()
、样式设置
Outputs
references/outputs.md
mo.output.append()
、控制台重定向

UI Elements

UI组件

APIReference FileDescription
Inputs
references/inputs.md
Sliders, text, dropdowns, tables, forms, etc.
Layouts
references/layouts.md
mo.hstack
, 
mo.vstack
, tabs, accordion, etc.
Media
references/media.md
Images, audio, video, PDF, downloads
Plotting
references/plotting.md
Altair, Plotly, matplotlib integration
Diagrams
references/diagrams.md
Mermaid diagrams
Status
references/status.md
Progress bars, spinners
API参考文档描述
Inputs
references/inputs.md
滑块、文本框、下拉菜单、表格、表单等
Layouts
references/layouts.md
mo.hstack
、
mo.vstack
、标签页、折叠面板等
Media
references/media.md
图片、音频、视频、PDF、下载功能
Plotting
references/plotting.md
与Altair、Plotly、matplotlib的集成
Diagrams
references/diagrams.md
Mermaid图表
Status
references/status.md
进度条、加载动画

Data

数据处理

APIReference FileDescription
SQL
references/sql.md
mo.sql()
for database and DataFrame queries
API参考文档描述
SQL
references/sql.md
mo.sql()
用于数据库和DataFrame查询

Advanced

进阶功能

APIReference FileDescription
Control Flow
references/control-flow.md
mo.stop()
, conditional execution
State
references/state.md
mo.state()
for UI synchronization
Caching
references/caching.md
@mo.cache
, 
@mo.persistent_cache
Query Params
references/query-params.md
mo.query_params()
for URL state
CLI Args
references/cli-args.md
mo.cli_args()
for script arguments
Watch
references/watch.md
mo.watch.file()
for reactive file monitoring
App
references/app.md
Embedding notebooks, 
mo.app_meta()
Cell
references/cell.md
Cross-notebook execution, testing
API参考文档描述
Control Flow
references/control-flow.md
mo.stop()
、条件执行
State
references/state.md
mo.state()
用于UI同步
Caching
references/caching.md
@mo.cache
、
@mo.persistent_cache
Query Params
references/query-params.md
mo.query_params()
用于URL状态管理
CLI Args
references/cli-args.md
mo.cli_args()
用于脚本参数处理
Watch
references/watch.md
mo.watch.file()
用于响应式文件监控
App
references/app.md
笔记本嵌入、
mo.app_meta()
Cell
references/cell.md
跨笔记本执行、测试

Quick Examples

快速示例

Basic UI

基础UI

python
import marimo as mo

slider = mo.ui.slider(0, 100, value=50, label="Threshold")
slider
python
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}")
undefined
mo.md(f"Selected value: {slider.value}")
undefined

Interactive Table

交互式表格

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

In another cell

在另一个单元格中

selected = table.value # Selected rows as DataFrame
undefined
selected = table.value # 选中的行以DataFrame形式返回
undefined

SQL Query

SQL查询

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

Conditional Execution

条件执行

python
mo.stop(form.value is None, mo.md("Submit the form to continue"))
python
mo.stop(form.value is None, mo.md("Submit the form to continue"))

Rest of cell runs only after form submission

仅在表单提交后，单元格剩余代码才会运行

undefined
undefined

Running as Apps

作为应用运行

bash
marimo run notebook.py                    # Local app
marimo export html-wasm notebook.py       # Static WASM app
Layout options: Vertical (default), Grid (drag-drop in editor), Slides.
bash
marimo run notebook.py                    # 本地运行应用
marimo export html-wasm notebook.py       # 导出为静态WASM应用
布局选项：垂直布局（默认）、网格布局（编辑器中可拖拽调整）、幻灯片布局。

Best Practices

最佳实践

  • Reactivity: Declare and mutate variables in the same cell
  • Performance: Use 
    @mo.cache
    for expensive computations
  • UI Gating: Use 
    mo.stop()
    to prevent expensive ops until ready
  • State: Avoid 
    mo.state()
    unless synchronizing multiple UI elements
  • Organization: Cell position doesn't matter; organize for readability
  • 响应式编程：在同一单元格中声明并修改变量
  • 性能优化：对耗时计算使用
    @mo.cache
  • UI管控：使用
    mo.stop()
    避免在准备就绪前执行昂贵操作
  • 状态管理：除非需要同步多个UI元素，否则避免使用
    mo.state()
  • 组织规范：单元格位置不影响执行顺序；请按可读性组织内容

Resources

资源