marimo 笔记本 WASM 兼容性检查器 - 确保 Python 代码在 WebAssembly 环境运行

wasm-compatibility by marimo-team/skills

361 周安装量

77 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/marimo-team/skills --skill wasm-compatibility

Python Web框架自动化代码规范

🇨🇳中文介绍

marimo 笔记本 WASM 兼容性检查器

检查 marimo 笔记本是否能在 WebAssembly (WASM) 环境中运行——包括 marimo 游乐场、社区云或导出的 WASM HTML。

使用说明

1. 读取笔记本

读取目标笔记本文件。如果用户未指定，请询问要检查哪个笔记本。

2. 提取依赖项

从以下两个来源收集笔记本依赖的每个包：

PEP 723 元数据——顶部的 # /// script 代码块：
```
# /// script
```
dependencies = [

"marimo",

"torch>=2.0.0",

]

///
导入语句——扫描所有单元格中的 import foo 和 from foo import bar。使用下表将导入名称映射到其 PyPI 发行版名称：

导入名称

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

3. 根据 Pyodide 检查每个包

对于每个依赖项，确定其是否能在 WASM 中运行：

它是否在 Python 标准库中？ 大多数标准库模块可用，但以下模块不可用：
- multiprocessing —— 浏览器沙盒不支持进程生成
- subprocess —— 同上
- threading —— 模拟实现，无真正并行性（警告，非硬性失败）
- sqlite3 —— 改用 apsw（Pyodide 中可用）
- pdb —— 不支持
- tkinter —— 浏览器中无 GUI 工具包
- readline —— 浏览器中无终端
它是否是 Pyodide 内置包？ 完整列表请参阅 pyodide-packages.md。这些包开箱即用。
它是否是纯 Python 包？ 仅包含 .py 文件（无编译的 C/Rust 扩展）的包可以通过 micropip 在运行时安装并正常工作。检查方法：在 PyPI 上查找 py3-none-any.whl 轮子文件（例如访问 https://pypi.org/project/<package>/#files）。如果只有平台特定的轮子文件（例如 cp312-cp312-manylinux），则该包包含原生扩展，可能无法工作。

可用的常见纯 Python 包（不在 Pyodide 内置包中，但可通过 micropip 安装）：

 * `plotly`、`seaborn`、`humanize`、`pendulum`、`arrow`、`tabulate`
 * `dataclasses-json`、`marshmallow`、`cattrs`、`pydantic`（内置）
 * `httpx`（内置）、`tenacity`、`backoff`、`wrapt`（内置）

4. 它是否包含未为 Pyodide 构建的 C/原生扩展？ 这些将无法工作。常见问题包：

 * `torch` / `pytorch`
 * `tensorflow`
 * `jax` / `jaxlib`
 * `psycopg2`（建议使用纯 Python 模式的 `psycopg`）
 * `mysqlclient`（建议使用 `pymysql`）
 * `uvloop`
 * `grpcio`
 * `psutil`

4. 检查 WASM 不兼容模式

扫描笔记本代码中无法在 WASM 中工作的模式：

模式	失败原因	建议
`subprocess.run(...)`、`os.system(...)`、`os.popen(...)`	浏览器中无法生成进程	移除或在非 WASM 检查后使用
`multiprocessing.Pool(...)`、`ProcessPoolExecutor`	无法进行进程分叉	使用单线程方法
`threading.Thread(...)`、`ThreadPoolExecutor`	模拟线程，无真正并行性	仅警告——可工作但无加速效果；对于 I/O 操作使用 `asyncio`
`open("/absolute/path/...")`、硬编码的本地文件路径	无真实文件系统；仅内存文件系统	通过 URL（`httpx`、`urllib`）获取数据或嵌入到笔记本中
`sqlite3.connect(...)`	标准库 sqlite3 不可用	使用 `apsw` 或 `duckdb`
`pdb.set_trace()`、`breakpoint()`	WASM 中无调试器	移除断点
读取环境变量（`os.environ[...]`、`os.getenv(...)`）	浏览器中环境变量不可用	使用 `mo.ui.text` 进行用户输入或硬编码默认值
期望真实文件的 `Path.home()`、`Path.cwd()`	仅虚拟文件系统	使用 URL 或嵌入数据
大型数据集加载（>100 MB）	总内存上限为 2 GB	使用较小样本或远程 API

5. 检查 PEP 723 元数据

WASM 笔记本应在 PEP 723 的 # /// script 代码块中列出所有依赖项，以便在笔记本启动时自动安装。检查以下问题：

缺少元数据： 如果笔记本没有 # /// script 代码块，发出警告建议添加。列出依赖项可确保在 WASM 中启动笔记本时自动安装——否则用户可能会看到导入错误。
缺少包： 如果导入了某个包但未在依赖项中列出，发出警告建议添加。注意：PEP 723 元数据中的版本固定和下限是可以的——marimo 在 WASM 中运行时将移除版本约束。

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

兼容性：通过 / 失败 / 警告

使用以下判定：

通过 —— 所有包和模式都与 WASM 兼容
警告 —— 可能兼容，但某些包无法验证为纯 Python（列出它们以便用户检查）
失败 —— 一个或多个包或模式明确不兼容

包报告 —— 包含以下列的表格：包、状态（正常 / 警告 / 失败）、备注

包	状态	备注
marimo	正常	WASM 运行时中可用
numpy	正常	Pyodide 内置
pandas	正常	Pyodide 内置
torch	失败	无 WASM 构建——需要原生 C++/CUDA 扩展
my-niche-lib	警告	不在 Pyodide 中；请验证其为纯 Python

代码问题 —— 列出发现的每个有问题的代码模式，包含单元格或行号以及修复建议。

建议 —— 如果笔记本失败，提供具体修复建议：

用 WASM 友好的替代方案替换不兼容的包
重写不兼容的代码模式
建议将繁重计算移至托管 API 并获取结果

WASM 笔记本通过浏览器中的 Pyodide 运行
内存上限为 2 GB
网络请求有效，但可能需要 CORS 兼容的端点
Chrome 具有最佳的 WASM 性能；Firefox、Edge、Safari 也受支持
micropip 可以在运行时从 PyPI 安装任何纯 Python 轮子文件
完整的 Pyodide 内置包列表，请参阅 pyodide-packages.md

🇺🇸English

WASM Compatibility Checker for marimo Notebooks

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

Instructions

1. Read the notebook

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

2. Extract dependencies

Collect every package the notebook depends on from both sources:

PEP 723 metadata — the # /// script block at the top:
```
# /// 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`

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

3. Check each package against 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 for the full list. These work out of the box.

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)

4. 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`

4. Check for WASM-incompatible patterns

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`

5. Check PEP 723 metadata

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.

6. Produce the report

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

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

Weekly Installs

343

Repository

marimo-team/skills

GitHub Stars

First Seen

Feb 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

claude-code278

codex205

opencode189

gemini-cli177

github-copilot175

kimi-cli174

xdrop 文件传输脚本：Bun 环境下安全上传下载工具，支持加密分享

20,700 周安装

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.

`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`