企业官网建设流程全解析

marimo 配置完全指南：笔记本级、用户级与项目级配置的层级体系与实战用法

【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo

marimo 提供两套配置体系：作用于所有笔记本的User Settings（用户配置）与仅作用于单个笔记本的Notebook Settings（笔记本配置），二者都可在 marimo 编辑器内可视化完成。本文以 docs/guides/configuration/index.md 为核心骨架，结合 marimo/_config/config.py、marimo/_config/manager.py 等源码实现，系统讲解配置文件位置、搜索顺序、配置优先级、pyproject.toml覆盖、PEP 723 脚本元数据、环境变量以及运行时与主题相关的核心配置项，帮助你完整掌握 marimo 的分层配置机制。

配置体系总览：两类配置、四个层级

marimo 的配置按作用范围分为两类：

• Notebook Settings（笔记本配置）：只对单个笔记本生效，随notebook.py文件存储，可随笔记本一起版本化与共享。
• User Settings（用户配置）：对所有 marimo 笔记本全局生效，存储在$XDG_CONFIG_HOME/marimo/marimo.toml（即通常的~/.config/marimo/marimo.toml）中。

从源码实现看，最终生效的配置由多个来源按固定顺序合并而成。在 marimo/_config/manager.py 的get_default_config_manager中可以看到，配置管理器由UserConfigManager（用户配置）、ProjectConfigManager（项目级pyproject.toml配置）、ScriptConfigManager（PEP 723 脚本元数据配置）、EnvConfigManager（环境变量配置）以及最后合入的SecurityConfigManager组成，合并结果通过merge_config（marimo/_config/config.py）层层叠加，后合入的层级优先生效。

因此完整的配置优先级可以概括为：

脚本元数据（PEP 723）> pyproject.toml 项目配置 > 用户配置 > 内置默认值（DEFAULT_CONFIG）

其中安全类强制项（如MARIMO_RESTRICT_SHARING）由SecurityConfigManager在最后合入，任何配置文件或运行时覆盖都无法撤销它——这是为基础设施管理员在容器、devpod 等场景预留的机器级管控面（见 marimo/_config/manager.py）。

Notebook settings：写在 notebook.py 里的笔记本级配置

笔记本配置针对单个 notebook 生效，存储在notebook.py文件中。通过右上角的笔记本菜单（⚙️）即可进入设置对话框，可配置：

• 笔记本宽度（Notebook width）
• 笔记本标题（Notebook title）
• 自定义 CSS
• 自定义 HTML Head
• 自动下载 HTML 快照

这些字段在底层对应 marimo/_ast/app_config.py 中的_AppConfig数据结构，其可用字段包括：

源码中_AppConfig仅接受白名单内的键，未知键会被忽略并发出警告（from_untrusted_dict，marimo/_ast/app_config.py），保证了配置的健壮性。除了 UI 外，这些字段也可直接写入marimo.App(...)构造器（如marimo.App(css_file="custom.css")），源码中的auto_download则对应设置面板里的"自动下载 HTML 快照"选项。

User settings：全局用户配置与配置文件搜索顺序

用户配置对所有笔记本全局生效，存储在$XDG_CONFIG_HOME/marimo/marimo.toml中。虽然可以直接编辑该 TOML 文件，但官方更推荐使用 marimo UI：点击笔记本设置菜单底部的 "User settings" 按钮，或按Cmd/Ctrl + k打开命令面板后输入"User settings"进入配置界面。

可定制的用户配置项包括：

• 运行时（Runtime）：含笔记本是否自动运行
• 快捷键（Hotkeys）
• 补全（Completion）：自动补全、AI copilot 等
• 显示（Display）：主题、字号、输出位置等
• 自动保存（Autosave）
• 包管理
• 服务器设置（Server settings）
• VIM 键位
• 格式化设置（Formatting）
• AI 辅助
• 代码片段（Snippets）
• 实验性功能（Experimental features）

配置文件查找顺序

marimo 按以下顺序搜索.marimo.toml配置文件（对应 marimo/_config/utils.py 中get_user_config_path的实现）：

1. 当前目录
2. 逐级向上的父目录（沿目录树向上移动）
3. 主目录（~/.marimo.toml）
4. XDG 目录（~/.config/marimo/marimo.toml或$XDG_CONFIG_HOME/marimo/marimo.toml）

搜索逻辑会先沿当前目录向上遍历（到达主目录即停止），再检查主目录，最后检查 XDG 路径，返回第一个命中的配置文件。若未找到任何配置文件，marimo 会以 XDG 兼容的方式在~/.config/marimo/marimo.toml（或$XDG_CONFIG_HOME/marimo下）自动创建一个（见 marimo/_config/utils.py 的get_or_create_user_config_path）。

值得注意的是，源码区分了"受信任的用户配置文件"与项目内的.marimo.toml：只有 XDG 配置文件和主目录下的~/.marimo.toml被视为用户所有（is_trusted_user_config_path，marimo/_config/utils.py），从工作目录向上搜索到的项目内配置文件属于不受信任来源，其中的缓存签名信任等密钥会被剥离（marimo/_config/manager.py），以防止克隆的仓库植入恶意信任配置。

用命令行查看与描述配置

查看当前生效的配置以及配置文件的位置：

marimo config show

查看所有用户配置选项的完整文档说明：

marimo config describe

marimo config show的实现（marimo/_cli/config/commands.py）会：若配置文件不存在则先自动创建（save_config_if_missing），然后输出两段内容——首先是来自pyproject.toml的Project overrides（若存在），其次是User config及其文件路径，便于你快速定位"当前设置从哪来"。marimo config describe则会递归遍历 marimo/_config/config.py 中MarimoConfig的所有 TypedDict 类型注解，将每个配置节的字段、类型与 docstring 文档渲染为结构化输出，是离线查阅全部配置项的最佳入口。

用 pyproject.toml 覆盖用户配置（项目级配置）

用户配置可以在项目级被pyproject.toml覆盖，适合在团队间共享配置或确保笔记本行为一致。覆盖操作需要直接编辑pyproject.toml文件完成。

例如，下面的pyproject.toml覆盖了用户配置中的格式化、显示与运行时设置：

[tool.marimo.formatting] line_length = 120 [tool.marimo.display] default_width = "full" [tool.marimo.runtime] default_sql_output = "native"

[tool.marimo.*]下的任何用户配置项都可以这样覆盖，具体字段可通过marimo config show查看。从源码看，ProjectConfigManager（marimo/_config/manager.py）会从当前目录向上查找最近的pyproject.toml（find_nearest_pyproject_toml），解析其中的[tool.marimo]段，并对pythonpath、dotenv、custom_css、vimrc等相对路径字段做基于pyproject.toml所在目录的绝对路径解析。此外配置结果带lru_cache，因此修改pyproject.toml后需要重启服务器才会生效。

附加文件浏览器根目录

如果希望 marimo 左侧文件浏览器显示工作目录之外的绝对目录，可在项目配置中添加：

[tool.marimo.file_browser] folders = [{ path = "/absolute/path/to/data", name = "Data" }]

若写在marimo.toml中，则使用[file_browser]节。name为可选显示名；无效或重复的路径会被自动忽略。这些附加根目录只影响文件浏览器面板，不能通过笔记本脚本元数据设置（底层由 marimo/_config/config.py 中的FileBrowserConfig/FolderConfig定义）。

脚本元数据配置（PEP 723）

还可以直接在笔记本文件顶部通过脚本元数据（PEP 723）配置 marimo 设置。在 notebook 顶部添加一个script块即可：

# /// script # [tool.marimo.runtime] # auto_instantiate = false # on_cell_change = "lazy" # [tool.marimo.display] # theme = "dark" # cell_output = "below" # ///

这是按笔记本内联配置的最高优先级手段，非常适合在分享应用或定义单个笔记本的强制行为时使用。ScriptConfigManager（marimo/_config/manager.py）会读取脚本头部的 TOML 注释块，并对其做白名单校验（allowlist_script_config）与auto_instantiate、isolate_apps、custom_css等字段的净化处理，防止不可信配置注入。

配置优先级

综合上面几节，完整的优先级规则是：

脚本元数据配置 > pyproject.toml 配置 > 用户配置

注意：被pyproject.toml或脚本元数据覆盖的设置，无法再通过 marimo 编辑器的设置菜单修改；即使在编辑器中改动，也不会生效。

运行时配置（Runtime）

通过笔记本设置菜单或笔记本底部栏，可以控制 marimo 何时以及如何运行单元格。完整说明见 运行时配置指南，此处给出最常用的几个核心项（对应RuntimeConfig，定义于 marimo/_config/config.py）：

启动时是否自动运行（auto_instantiate）

切换该设置可控制用marimo edit打开的笔记本是否在启动时自动运行全部单元格。默认值为True；当用marimo run将笔记本作为应用分享时，此设置不生效。

单元格变更时：关闭自动运行（懒执行，on_cell_change）

默认情况下，当一个单元格被运行或 UI 元素被交互时，marimo 会自动运行引用了其变量的所有下游单元格。将设置菜单中的"On cell change"设为"lazy"可以关闭这种自动执行：

• 懒运行时，运行某个单元格只会把受影响的单元格标记为stale（过期），而不会自动运行它们；
• 单元格只在输出真正被需要时才执行——如果你运行一个存在 stale 祖先的单元格，这些祖先会一并运行，确保你不会用到过期输入；
• 也可以随时点击笔记本的运行按钮或使用快捷键来运行所有 stale 单元格。

何时使用懒执行？当笔记本包含昂贵单元格时，懒执行可以显著提升编辑体验。源码中该字段类型为Literal["lazy", "autorun"]，默认"autorun"。

提示：除运行时配置外，marimo 还提供可选缓存机制（mo.cache内存缓存与mo.persistent_cache磁盘缓存）来应对昂贵或带副作用的笔记本，详见缓存指南。

缓存所有单元格（cache_cells）

默认情况下，marimo 只缓存你显式用mo.cache或mo.persistent_cache装饰的函数或代码块。若希望 marimo 尝试缓存笔记本中每个已执行的单元格，可将运行时配置设为：

[tool.marimo.runtime] cache_cells = true

既可写在pyproject.toml，也可写在笔记本的 PEP 723 元数据中。具体行为与当前限制参见自动单元格缓存。

模块变更时（auto_reload）

启用模块自动重载后，当你编辑 Python 文件时 marimo 会自动运行受影响单元格。基于静态分析，reloader 只运行被编辑所影响的单元格，并且是递归的——不仅跟踪笔记本直接导入的模块，还跟踪这些模块再导入的模块。两种模式：

1. autorun：自动重新运行受模块修改影响的单元格；
2. lazy：把受影响的单元格标记为 stale，提示你哪些单元格需要重跑。

源码中auto_reload的类型为Literal["off", "lazy", "autorun"]，默认"off"。在merge_config中还有向后兼容逻辑：旧配置中的布尔值False会被转为"off"，True/"detect"会被转为"lazy"（marimo/_config/config.py）。自动重载适合"在 Python 模块中开发复杂逻辑、把 marimo 笔记本当作 DAG 或主脚本来编排"的工作流。

Python 路径（pythonpath）

默认情况下 marimo 不向 Python 路径添加任何额外目录，以保证marimo edit nb.py与python nb.py行为一致。如需添加目录，可在运行时配置中设置pythonpath，这些目录会被插入sys.path头部，类似PYTHONPATH环境变量的行为：

[tool.marimo.runtime] pythonpath = ["project/src"]

从源码看，ProjectConfigManager._resolve_pythonpath会把相对路径解析为相对于pyproject.toml的绝对路径（marimo/_config/manager.py）。

建议：能不动路径就不动路径。如果要在笔记本旁的独立目录中开发模块，更推荐创建包并把 marimo 作为项目依赖：

uv init --lib my_package cd my_package uv add --dev marimo uv run marimo edit notebook.py # my_package 在笔记本环境中可用

多包场景可考虑配置 uv workspaces。

环境变量加载（.env 文件）

marimo 支持从.env文件加载环境变量，适合管理不应提交到版本控制的配置（如 API 密钥、数据库凭据）。pyproject.toml旁边的.env默认会被加载；如需多个或不同位置，可在配置中显式指定：

[tool.marimo.runtime] dotenv = [".env", ".env.testing"]

从源码看，dotenv的默认值取决于运行时环境：找到pyproject.toml时默认为[".env"]，否则为[]（marimo/_config/config.py）。来自dotenv的环境变量还会在 UI 中创建数据库连接时自动呈现。配置的.env路径同样会被解析为相对于pyproject.toml的绝对路径。

显示、主题与自定义 HTML Head

主题化（Theming）

marimo 提供基础的主题支持：可在配置下拉菜单的Custom CSS字段中填写相对路径的 CSS 文件，保存后整个笔记本立即应用该样式；等价地，也可在代码中通过marimo.App(css_file="custom.css")指定。主题的完整说明见主题指南。

项目级主题：也可在项目配置中设置custom_css字段，为项目内所有打开的笔记本统一应用样式（不会随笔记本分享给他人）：

[tool.marimo.display] custom_css = ["additional.css"]

公开的 CSS 变量：作为 theming "公共 API"，目前仅支持以下三个 CSS 变量：

--marimo-monospace-font --marimo-text-font --marimo-heading-font

警告：除上述变量外，其他 CSS 变量或类名无法保证跨版本稳定。

示例——一个修改笔记本字体的自定义 CSS 文件：

/* 从 Google Fonts 加载 Inter */ @import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap'); :root { --marimo-heading-font: 'Inter', sans-serif; } /* 增大段落字号并改变颜色 */ .paragraph { font-size: 1.2rem; color: light-dark(navy, pink); }

强制暗色模式：若想为某个应用强制指定主题，可通过脚本元数据覆盖 marimo 配置（theme支持light/dark/system，见 marimo/_config/config.py）：

# /// script # [tool.marimo.display] # theme = "dark" # ///

定位单元格：可以使用data-cell-name属性定位特定单元格，用data-cell-role="output"定位单元格输出：

/* 定位名为 "My Cell" 的单元格 */ [data-cell-name='my_cell'] { background-color: light-dark(navy, pink); } /* 定位名为 "My Cell" 的单元格的输出 */ [data-cell-name='my_cell'] [data-cell-role='output'] { background-color: light-dark(navy, pink); }

自定义 HTML Head：进一步地，可在笔记本<head>中注入自定义 HTML，从而添加分析脚本、自定义字体、meta 标签或外部脚本等功能，详见自定义 HTML Head 指南。

其他显示配置项

DisplayConfig（marimo/_config/config.py）还包含以下常用项：theme（light/dark/system）、code_editor_font_size（编辑器字号）、cell_output（输出显示在单元格above或below）、default_width（normal/compact/medium/full/columns）、dataframes（rich或plain渲染）、default_table_page_size、default_table_max_columns、reference_highlighting（高亮响应式变量引用）、code_lens以及locale（日期格式与国际化区域设置，如en-US、de-DE）。这些字段均可出现在pyproject.toml的[tool.marimo.display]节或 PEP 723 脚本元数据中。

环境变量：高级配置

marimo 支持以下环境变量进行高级配置：

前两个输出大小限制变量已弃用，应改用pyproject.toml中的运行时配置（output_max_bytes、std_stream_max_bytes，其默认值即读取自这两个环境变量，见 marimo/_config/config.py 的DEFAULT_CONFIG）。MARIMO_SESSION_COOKIE_SECURE与MARIMO_SESSION_SECRET在 marimo/_config/settings.py 中被读取为全局设置；MARIMO_SERVER_TRANSPORT则由EnvConfigManager映射到server.transport配置（合法值仅websocket与sse，非法值会被忽略并告警，见 marimo/_config/manager.py）。从源码看，使用sse传输时终端、LSP 与实时协作仍需要 WebSocket，RTC 在sse模式下会被禁用（marimo/_config/config.py）。

此外，源码 marimo/_config/settings.py 还暴露了MARIMO_RESTRICT_SHARING：设为true时会在所有会话中隐藏外部代码分享入口（可分享 WASM 链接、molab、HTML 发布），由SecurityConfigManager强制生效，属于面向基础设施管理员的机器级策略控制。

实战建议

• .marimo.toml文件可以进行版本控制，便于在团队间共享一致的配置；
• 应用（App）配置可随笔记本一起提交，确保外观一致（笔记本设置存储在notebook.py中，天然随代码库版本化）；
• 团队协作时，优先在pyproject.toml的[tool.marimo.*]节中声明项目级默认值，用户个人偏好保留在各自的marimo.toml中——两者按"脚本元数据 > pyproject.toml > 用户配置"的优先级叠加，既保证团队一致性，又尊重个人习惯；
• 排查配置问题时，先用marimo config show确认各层配置的来源与最终值，再用marimo config describe查阅全部可配置字段的官方说明；
• 修改pyproject.toml或脚本元数据后需要重启 marimo 服务器才会生效（源码中项目配置与脚本配置均带缓存）。

【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo