
本文介绍如何利用 uv 的工具管理功能(uvx)将 marimo 笔记本打包为无需预装依赖的单文件可执行脚本,实现一键启动、自动安装依赖、开箱即用。
本文介绍如何利用 uv 的工具管理功能(uvx)将 marimo 笔记本打包为无需预装依赖的单文件可执行脚本,实现一键启动、自动安装依赖、开箱即用。
在 Python 生态中,分发交互式笔记本常面临环境依赖难题:用户需手动安装 marimo 及其依赖,降低了使用门槛。uv 提供了轻量高效的解决方案——通过 uvx(即 uv tool run)命令,可将任意 PyPI 工具(如 marimo)作为“自包含工具”直接调用,自动解析 # /// script 元数据、创建临时隔离环境、安装依赖并执行,全程无需用户干预。
关键在于区分 uv run 与 uvx 的语义:
-
uv run用于运行当前项目中的脚本或命令,依赖项目根目录下的pyproject.toml或已激活的虚拟环境,不适用于无项目上下文的单文件场景; -
uvx(等价于uv tool run)专为按需调用第三方工具设计,会基于脚本头部的# /// script声明自动构建最小运行环境,并将工具二进制(如marimo)注入PATH,完美适配自包含脚本需求。
✅ 正确写法如下(保存为 notebook.py,赋予可执行权限 chmod +x notebook.py):
#!/usr/bin/env -S uvx marimo edit notebook.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "marimo>=0.8.0",
# "numpy>=1.24",
# "matplotlib>=3.7",
# ]
# ///
import marimo
app = marimo.App()
@app.cell
def _():
import marimo as mo
return mo
@app.cell
def _():
mo.md("## Hello, Marimo! ?\nThis notebook runs with zero setup.")
return
⚠️ 注意事项:
- 确保系统已安装 uv(推荐
curl -LsSf https://astral.sh/uv/install.sh | sh);- 脚本必须以
#!/usr/bin/env -S uvx ...开头,且-S参数允许uvx正确解析后续空格分隔的参数;uvx会缓存依赖至全局uvcache(默认~/.cache/uv),首次运行稍慢,后续秒启;- 若需指定 Python 版本或额外 pip 参数(如
--index-url),可在uvx后添加,例如:uvx --python 3.12 marimo edit notebook.py;- 不支持 Windows PowerShell 直接双击运行,建议通过终端执行(Windows 用户可用 WSL 或
uvx marimo edit notebook.py命令)。
该方案真正实现了“一个文件即应用”:用户只需下载 .py 文件并执行,uvx 自动完成环境准备与服务启动,marimo Web 界面随即在浏览器中打开。结合 Marimo 的声明式单元与实时反馈特性,这种极简分发模式特别适合教学演示、内部工具共享或快速原型交付。










