企业官网建设流程全解析

如何用 uv 运行 marimo notebook：uvx 与内联脚本元数据的集成方法

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

marimo 是一个开源 Python notebook，以纯 Python 脚本形式保存，可以像传统软件一样用 Git 做版本管理、作为脚本运行、或作为 app 分享。正因为它就是普通.py文件，uv 可以用两条直接的路径来运行它：用uvx在一次性隔离环境里临时启动 marimo，或者用 uv 的内联脚本元数据（inline script metadata）让 notebook 自带依赖声明，随时以脚本方式执行。本文面向已经拿到一个 marimo notebook（一个.py文件）、希望不手动管理虚拟环境就能运行它的开发者。

前提：先装好 uv

两条路径都依赖 uv。官方文档 Installing uv 提供了多种安装方式，macOS 和 Linux 上最常用的是独立安装脚本：

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 上则使用 PowerShell：

PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

该脚本会下载并执行安装程序，可能修改你的 shell 配置文件；官方文档提示可以先用curl -LsSf https://astral.sh/uv/install.sh | less审查脚本内容再执行。也支持 PyPI（pipx install uv或pip install uv）、Homebrew（brew install uv）、WinGet、Scoop、Cargo 等方式，按需选择即可。

路径一：用 uvx 临时运行 marimo

如果只是临时使用 marimo，不需要把它装进任何持久环境。Using uv with marimo 给出的命令是：

$ uvx marimo edit

这会启动一个 marimo server，marimo 本身被安装在一个临时的隔离环境里。uvx是uv tool run的等价别名（见 Using tools）：uvx marimo edit与uv tool run marimo edit完全等价，区别只是uvx更短。

如果已经有具体的 notebook，直接带上文件路径启动：

$ uvx marimo edit my_notebook.py

其中my_notebook.py是你的 marimo notebook 文件（marimo notebook 就是普通 Python 脚本）。

uvx路径适用于临时、即开即用的场景。文档同时说明了一个边界条件：如果你在项目里运行、且工具需要项目本身被安装，应使用uv run而不是uvx——因为uvx的工具环境与项目是隔离的。对临时启动 marimo 来说这不是问题。

路径二：给 notebook 写入内联脚本元数据

marimo notebook 既然以 Python 脚本形式存在，就可以用 uv 支持的内联脚本元数据在文件内部声明自己的依赖，做到自包含。这一步的完整机制见 Running scripts。

用 uv add --script 声明依赖

假设你的 notebook 需要numpy，执行：

$ uv add --script my_notebook.py numpy

uv add --script会在脚本顶部写入一个 TOML 格式的script元数据块，声明依赖。按脚本指南中的格式，写入后的文件形如：

# /// script # dependencies = [ # "numpy", # ] # /// import marimo __generated_with = "..." if __name__ == "__main__": marimo.run(main)

以上结构参照文档中uv add --script生成的元数据块样式；实际内容以你执行命令后文件为准。注意文档特别指出：dependencies字段即使为空也必须注明。

用 --sandbox 交互编辑

带有内联脚本元数据的 notebook 要用下面的方式打开交互编辑：

$ uvx marimo edit --sandbox my_notebook.py

执行后会发生三件事（均来自 marimo 集成文档）：

1. marimo 自动调用 uv，在一个隔离的虚拟环境中启动 notebook，依赖就是脚本元数据里声明的那些；
2. 在 marimo 的 UI 里安装的任何包，都会自动回写到 notebook 的脚本元数据中，依赖声明随 UI 操作自动更新；
3. 你不需要手工创建或管理这个虚拟环境。

把 notebook 当脚本直接运行

有了内联元数据，notebook 可以不打开交互式会话、直接以 Python 脚本方式执行：

$ uv run my_notebook.py

这条命令会执行 notebook 的全部单元格但不启动浏览器交互会话，适合把 notebook 用进批处理流程。

一个值得记住的行为细节：只要脚本带内联脚本元数据，即使在 uv project 目录里执行uv run，项目的依赖也会被忽略，不需要额外加--no-project（见 Running scripts）。

验证方式

文档给出的可核对结果是：

• 执行uvx marimo edit或uvx marimo edit my_notebook.py后，marimo server 在浏览器中启动，即视为隔离环境中的 marimo 启动成功；
• 使用--sandbox打开带元数据的 notebook 后，在 marimo UI 中安装一个包，重新查看my_notebook.py文件顶部，dependencies列表里应出现该包——这是脚本元数据回写生效的直接证据；
• uv run my_notebook.py以脚本方式跑完全部单元格、不打开浏览器交互会话。

两条路径的选择与限制

两个限制来自文档原文：

• uvx的工具环境与项目隔离。如果你在 uv project 中工作并希望 notebook 能 import 项目自己的模块，应改用uv run marimo edit my_notebook.py（marimo 作为项目依赖时），或uv run --with marimo marimo edit my_notebook.py（marimo 不是项目依赖时）。后者有个明确警告：这种跑法下通过 marimo UI 安装的包不会进入项目依赖，下次启动可能丢失。
• 非项目虚拟环境（uv venv+uv pip install marimo后再uv run marimo edit）是文档提供的第三种跑法，marimo UI 装包会用uv pip install写进该环境；但它与本文两条主线不冲突，属于另一种部署形态，此处仅列出备查。

相关文档：Using uv with marimo、Running scripts、Using tools、Projects 概念。

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv