
本文介绍如何利用 uv 的 uvx 命令构建真正自包含的 Marimo 笔记本——无需预装依赖,运行即装即启,完美解决分发难题。
本文介绍如何利用 uv 的 `uvx` 命令构建真正自包含的 marimo 笔记本——无需预装依赖,运行即装即启,完美解决分发难题。
在 Python 生态中,实现“一个文件、开箱即用”的交互式笔记本长期面临依赖管理痛点。你可能已尝试使用 uv run 启动 Marimo,但遇到 error: Failed to spawn: 'marimo' — No such file or directory 错误——这并非环境缺失,而是命令语义误用所致。
核心问题在于:uv run 旨在运行当前项目上下文中的脚本或命令(需 pyproject.toml 或入口点注册),而你的 .py 文件是独立脚本,marimo 并未作为可执行工具被识别。正确解法是使用 uvx(即 uv tool run):它专为按需安装并运行第三方 CLI 工具设计,会自动从 PyPI 安装 marimo 到 uv 的全局工具缓存,并确保其二进制路径可用。
✅ 正确写法如下(保存为 notebook.py,赋予可执行权限 chmod +x notebook.py):
#!/usr/bin/env -S uvx marimo edit main.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "marimo",
# "numpy",
# "matplotlib",
# ]
# ///
import marimo
app = marimo.App()
@app.cell
def _():
import marimo as mo
return mo
@app.cell
def _():
mo.md("## Hello, Marimo!")
return⚠️ 关键注意事项:
-
必须使用
uvx,而非uv run:uvx是 uv 的工具执行器,会智能解析# /// script元数据,安装依赖并调用marimo edit; -
main.py是当前文件自身:uvx marimo edit main.py中的main.py即该脚本文件名(建议统一命名,如notebook.py,并在 shebang 中同步更新); -
首次运行会自动安装:
uvx将检查本地缓存,若无marimo或版本不匹配,会静默下载安装(约 1–3 秒),后续运行秒级启动; -
跨平台兼容:Linux/macOS 直接执行
./notebook.py;Windows 用户可改用uvx marimo edit notebook.py命令行调用(或通过python -m uvx marimo edit notebook.py兼容)。
? 进阶提示:若需指定 Marimo 版本(如避免未来 breaking change),可在 dependencies 中写明:"marimo>=0.7.0,;如需静默启动浏览器,可追加 <code>--no-browser 参数:uvx marimo edit notebook.py --no-browser。
至此,你已拥有一个零配置、免安装、可双击/终端一键运行的自包含 Marimo 笔记本——分发时只需发送单个 .py 文件,收件人无需了解 uv、pip 或虚拟环境,真正实现“所见即所得”的协作体验。

















