jupyter-to-marimo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Converting Jupyter Notebooks to Marimo

将Jupyter笔记本转换为Marimo笔记本

IMPORTANT: When asked to translate a notebook, ALWAYS run

uvx marimo convert <notebook.ipynb> -o <notebook.py>

FIRST before reading any files. This saves precious tokens - reading large notebooks can consume 30k+ tokens, while the converted .py file is much smaller and easier to work with.

重要提示：当需要转换笔记本时，务必先运行

uvx marimo convert <notebook.ipynb> -o <notebook.py>

，再读取任何文件。这能节省宝贵的token——读取大型笔记本可能会消耗30k以上的token，而转换后的.py文件体积更小，更易于处理。

Steps

转换步骤

Convert using the CLI

Run the marimo convert command via

uvx

so no install is needed:

bash

uvx marimo convert <notebook.ipynb> -o <notebook.py>

This generates a marimo-compatible

.py

file from the Jupyter notebook.

Run
marimo check
on the output

bash

uvx marimo check <notebook.py>

Fix any issues that are reported before continuing.

Review and clean up the converted notebook

Read the generated

.py

file and apply the following improvements:

Ensure the script metadata block lists all required packages. The converter may miss some.
Drop leftover Jupyter artifacts like
```
display()
```
calls, or
```
%magic
```
commands that don't apply in marimo.
Make sure the final expression of each cell is the value to render. Indented or conditional expressions won't display.
If the original notebook requires environment variables via an input, consider adding the
```
EnvConfig
```
widget from wigglystuff. Details can be found here.
If the original notebook uses ipywidgets, replace them with corresponding ui from marimo. A slider, for example, would be replaced with
```
mo.ui.slider()
```
.

Run
marimo check
again after your edits to confirm nothing was broken.

通过CLI进行转换

通过

uvx

运行marimo转换命令，无需提前安装：

bash

uvx marimo convert <notebook.ipynb> -o <notebook.py>

这会从Jupyter笔记本生成一个兼容marimo的

.py

文件。

对输出文件运行
marimo check
命令

bash

uvx marimo check <notebook.py>

在继续下一步之前，修复所有检测到的问题。

检查并清理转换后的笔记本

读取生成的

.py

文件并进行以下优化：

确保脚本元数据块列出了所有必需的包。转换工具可能会遗漏部分依赖。
移除残留的Jupyter相关代码，比如
```
display()
```
调用，或者在marimo中不适用的
```
%magic
```
命令。
确保每个单元格的最后一个表达式是需要渲染的值。缩进或条件表达式不会被显示。
如果原始笔记本需要通过输入设置环境变量，可以考虑添加wigglystuff中的
```
EnvConfig
```
组件。详情可查看这里。
如果原始笔记本使用了ipywidgets，将其替换为marimo对应的UI组件。例如，滑块可以替换为
```
mo.ui.slider()
```
。

编辑完成后再次运行
marimo check
，确认没有引入新的问题。