wasm-compatibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WASM Compatibility Checker for marimo Notebooks

面向marimo Notebooks的WASM兼容性检查器

Check whether a marimo notebook can run in a WebAssembly (WASM) environment — the marimo playground, community cloud, or exported WASM HTML.

检查marimo notebook能否在WebAssembly（WASM）环境中运行——包括marimo playground、社区云，或者导出的WASM HTML文件。

Instructions

使用说明

1. Read the notebook

1. 读取notebook

Read the target notebook file. If the user doesn't specify one, ask which notebook to check.

读取目标notebook文件。如果用户没有指定具体文件，询问要检查的notebook名称。

2. Extract dependencies

2. 提取依赖项

Collect every package the notebook depends on from both sources:

PEP 723 metadata — the

# /// script

block at the top:

python

# /// script
# dependencies = [
#     "marimo",
#     "torch>=2.0.0",
# ]
# ///

Import statements — scan all cells for

import foo

and

from foo import bar

. Map import names to their PyPI distribution name using this table:

Import name	Distribution name
`sklearn`	`scikit-learn`
`skimage`	`scikit-image`
`cv2`	`opencv-python`
`PIL`	`Pillow`
`bs4`	`beautifulsoup4`
`yaml`	`pyyaml`
`dateutil`	`python-dateutil`
`attr` / `attrs`	`attrs`
`gi`	`PyGObject`
`serial`	`pyserial`
`usb`	`pyusb`
`wx`	`wxPython`

For most other packages, the import name matches the distribution name.

从以下两个来源收集notebook依赖的所有包：

PEP 723元数据——文件顶部的

# /// script

代码块：

python

# /// script
# dependencies = [
#     "marimo",
#     "torch>=2.0.0",
# ]
# ///

导入语句——扫描所有单元格的
```
import foo
```
和
```
from foo import bar
```
语句。通过下表将导入名称映射到对应的PyPI发行包名：
导入名称发行包名
sklearn
scikit-learn
skimage
scikit-image
cv2
opencv-python
PIL
Pillow
bs4
beautifulsoup4
yaml
pyyaml
dateutil
python-dateutil
attr
/
attrs
attrs
gi
PyGObject
serial
pyserial
usb
pyusb
wx
wxPython
绝大多数其他包的导入名称和发行包名是一致的。

3. Check each package against Pyodide

3. 对照Pyodide检查每个包

For each dependency, determine if it can run in WASM:

Is it in the Python standard library? Most stdlib modules work, but these do not:
- ```
multiprocessing
```
  — browser sandbox has no process spawning
- ```
subprocess
```
  — same reason
- ```
threading
```
  — emulated, no real parallelism (WARN, not a hard fail)
- ```
sqlite3
```
  — use
```
apsw
```
  instead (available in Pyodide)
- ```
pdb
```
  — not supported
- ```
tkinter
```
  — no GUI toolkit in browser
- ```
readline
```
  — no terminal in browser
Is it a Pyodide built-in package? See pyodide-packages.md for the full list. These work out of the box.
Is it a pure-Python package? Packages with only
```
.py
```
files (no compiled C/Rust extensions) can be installed at runtime via
```
micropip
```
and will work. To check: look for a
```
py3-none-any.whl
```
wheel on PyPI (e.g. visit
```
https://pypi.org/project/<package>/#files
```
). If the only wheels are platform-specific (e.g.
```
cp312-cp312-manylinux
```
), the package has native extensions and likely won't work.
Common pure-Python packages that work (not in Pyodide built-ins but installable via micropip):
- ```
plotly
```
  ,
```
seaborn
```
  ,
```
humanize
```
  ,
```
pendulum
```
  ,
```
arrow
```
  ,
```
tabulate
```
- ```
dataclasses-json
```
  ,
```
marshmallow
```
  ,
```
cattrs
```
  ,
```
pydantic
```
  (built-in)
- ```
httpx
```
  (built-in),
```
tenacity
```
  ,
```
backoff
```
  ,
```
wrapt
```
  (built-in)
Does it have C/native extensions not built for Pyodide? These will not work. Common culprits:
- ```
torch
```
  /
```
pytorch
```
- ```
tensorflow
```
- ```
jax
```
  /
```
jaxlib
```
- ```
psycopg2
```
  (suggest
```
psycopg
```
  with pure-Python mode)
- ```
mysqlclient
```
  (suggest
```
pymysql
```
  )
- ```
uvloop
```
- ```
grpcio
```
- ```
psutil
```

对每个依赖项，判断其能否在WASM中运行：

是否属于Python标准库？ 绝大多数标准库模块都可以运行，但以下模块不可用：
- ```
multiprocessing
```
  ——浏览器沙箱不支持进程创建
- ```
subprocess
```
  ——原因同上
- ```
threading
```
  ——为模拟实现，无真实并行能力（仅警告，不属于强制失败项）
- ```
sqlite3
```
  ——可使用Pyodide中提供的
```
apsw
```
  替代
- ```
pdb
```
  ——不支持
- ```
tkinter
```
  ——浏览器中无GUI工具包
- ```
readline
```
  ——浏览器中无终端环境
是否是Pyodide内置包？ 完整列表请查看pyodide-packages.md，这些包可以开箱即用。
是否是纯Python包？ 仅包含
```
.py
```
文件（没有编译过的C/Rust扩展）的包可以在运行时通过
```
micropip
```
安装，正常运行。检查方法：在PyPI上查找是否有
```
py3-none-any.whl
```
格式的wheel包（比如访问
```
https://pypi.org/project/<package>/#files
```
）。如果只有平台特定的wheel包（比如
```
cp312-cp312-manylinux
```
），说明该包包含原生扩展，大概率无法运行。
常见可正常运行的纯Python包（不属于Pyodide内置，但可通过micropip安装）：
- ```
plotly
```
  ,
```
seaborn
```
  ,
```
humanize
```
  ,
```
pendulum
```
  ,
```
arrow
```
  ,
```
tabulate
```
- ```
dataclasses-json
```
  ,
```
marshmallow
```
  ,
```
cattrs
```
  ,
```
pydantic
```
  （内置）
- ```
httpx
```
  （内置）,
```
tenacity
```
  ,
```
backoff
```
  ,
```
wrapt
```
  （内置）
是否包含未适配Pyodide的C/原生扩展？ 这类包无法运行，常见的包括：
- ```
torch
```
  /
```
pytorch
```
- ```
tensorflow
```
- ```
jax
```
  /
```
jaxlib
```
- ```
psycopg2
```
  （建议使用纯Python模式的
```
psycopg
```
  替代）
- ```
mysqlclient
```
  （建议使用
```
pymysql
```
  替代）
- ```
uvloop
```
- ```
grpcio
```
- ```
psutil
```

4. Check for WASM-incompatible patterns

4. 检查不兼容WASM的代码模式

Scan the notebook code for patterns that won't work in WASM:

Pattern	Why it fails	Suggestion
`subprocess.run(...)` , `os.system(...)` , `os.popen(...)`	No process spawning in browser	Remove or gate behind a non-WASM check
`multiprocessing.Pool(...)` , `ProcessPoolExecutor`	No process forking	Use single-threaded approach
`threading.Thread(...)` , `ThreadPoolExecutor`	Emulated threads, no real parallelism	WARN only — works but no speedup; use `asyncio` for I/O
`open("/absolute/path/...")` , hard-coded local file paths	No real filesystem; only in-memory fs	Fetch data via URL ( `httpx` , `urllib` ) or embed in notebook
`sqlite3.connect(...)`	stdlib sqlite3 unavailable	Use `apsw` or `duckdb`
`pdb.set_trace()` , `breakpoint()`	No debugger in WASM	Remove breakpoints
Reading env vars ( `os.environ[...]` , `os.getenv(...)` )	Environment variables not available in browser	Use `mo.ui.text` for user input or hardcode defaults
`Path.home()` , `Path.cwd()` with real file expectations	Virtual filesystem only	Use URLs or embedded data
Large dataset loads (>100 MB)	2 GB total memory cap	Use smaller samples or remote APIs

扫描notebook代码中无法在WASM中运行的模式：

代码模式	失败原因	修复建议
`subprocess.run(...)` , `os.system(...)` , `os.popen(...)`	浏览器不支持进程创建	移除相关代码，或添加非WASM环境判断做隔离
`multiprocessing.Pool(...)` , `ProcessPoolExecutor`	不支持进程分叉	改用单线程实现方案
`threading.Thread(...)` , `ThreadPoolExecutor`	线程为模拟实现，无真实并行能力	仅警告——可运行但无速度提升；IO密集型场景可改用 `asyncio`
`open("/absolute/path/...")` 、硬编码的本地文件路径	无真实文件系统，仅存在内存文件系统	通过URL（ `httpx` 、 `urllib` ）拉取数据，或者将数据嵌入notebook
`sqlite3.connect(...)`	标准库sqlite3不可用	使用 `apsw` 或 `duckdb` 替代
`pdb.set_trace()` , `breakpoint()`	WASM环境中无调试器	移除断点
读取环境变量（ `os.environ[...]` 、 `os.getenv(...)` ）	浏览器中没有环境变量	使用 `mo.ui.text` 接收用户输入，或者硬编码默认值
对 `Path.home()` 、 `Path.cwd()` 有真实文件系统预期	仅存在虚拟文件系统	使用URL或嵌入数据
加载大于100MB的数据集	总内存上限为2GB	使用更小的样本，或者调用远程API获取数据

5. Check PEP 723 metadata

5. 检查PEP 723元数据

WASM notebooks should list all dependencies in the PEP 723

# /// script

block so they are automatically installed when the notebook starts. Check for these issues:

Missing metadata: If the notebook has no
```
# /// script
```
block, emit a WARN recommending one. Listing dependencies ensures they are auto-installed when the notebook starts in WASM — without it, users may see import errors.
Missing packages: If a package is imported but not listed in the dependencies, emit a WARN suggesting it be added. Note: version pins and lower bounds in PEP 723 metadata are fine — marimo strips version constraints when running in WASM.

WASM notebook应当把所有依赖都列在PEP 723的

# /// script

块中，这样notebook启动时会自动安装这些依赖。检查以下问题：

缺少元数据： 如果notebook没有
```
# /// script
```
块，发出WARN警告建议添加。列出依赖可以保证WASM环境下启动notebook时自动安装依赖——没有的话用户可能会遇到导入错误。
缺少包： 如果某个包被导入了，但没有列在依赖项中，发出WARN警告建议添加。注意：PEP 723元数据中的版本锁定和最低版本限制是没问题的——marimo在WASM环境中运行时会移除版本约束。

6. Produce the report

6. 生成报告

Output a clear, actionable report with these sections:

Compatibility: PASS / FAIL / WARN

Use these verdicts:

PASS — all packages and patterns are WASM-compatible
WARN — likely compatible, but some packages could not be verified as pure-Python (list them so the user can check)
FAIL — one or more packages or patterns are definitely incompatible

Package Report — table with columns: Package, Status (OK / WARN / FAIL), Notes

Example:

Package	Status	Notes
marimo	OK	Available in WASM runtime
numpy	OK	Pyodide built-in
pandas	OK	Pyodide built-in
torch	FAIL	No WASM build — requires native C++/CUDA extensions
my-niche-lib	WARN	Not in Pyodide; verify it is pure-Python

Code Issues — list each problematic code pattern found, with the cell or line and a suggested fix.

Recommendations — if the notebook fails, suggest concrete fixes:

Replace incompatible packages with WASM-friendly alternatives
Rewrite incompatible code patterns
Suggest moving heavy computation to a hosted API and fetching results

输出清晰、可执行的报告，包含以下部分：

兼容性：PASS / FAIL / WARN

使用以下判定标准：

PASS——所有包和代码模式都兼容WASM
WARN——大概率兼容，但部分包无法验证是否为纯Python（列出这些包方便用户自行检查）
FAIL——存在一个或多个明确不兼容的包或代码模式

包报告——表格包含以下列：包名、状态（OK / WARN / FAIL）、说明

示例：

包名	状态	说明
marimo	OK	WASM运行时内置提供
numpy	OK	Pyodide内置包
pandas	OK	Pyodide内置包
torch	FAIL	无WASM构建版本——依赖原生C++/CUDA扩展
my-niche-lib	WARN	不在Pyodide内置列表中，请自行验证是否为纯Python包

代码问题——列出所有找到的有问题的代码模式，标注所在单元格或行数，以及对应的修复建议。

建议——如果notebook检测不通过，给出具体的修复方案：

将不兼容的包替换为WASM友好的替代方案
重写不兼容的代码模式
建议将重度计算任务迁移到托管API，再拉取运行结果

Additional context

额外说明

WASM notebooks run via Pyodide in the browser
Memory is capped at 2 GB
Network requests work but may need CORS-compatible endpoints
Chrome has the best WASM performance; Firefox, Edge, Safari also supported
```
micropip
```
can install any pure-Python wheel from PyPI at runtime
For the full Pyodide built-in package list, see pyodide-packages.md

WASM notebook通过浏览器中的Pyodide运行
内存上限为2GB
网络请求可以正常运行，但可能需要CORS兼容的端点
Chrome的WASM性能最佳；Firefox、Edge、Safari也支持
```
micropip
```
可以在运行时从PyPI安装任何纯Python wheel包
完整的Pyodide内置包列表请查看pyodide-packages.md