使用 Docker 容器化运行 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 是一个响应式 Python 笔记本框架而 Docker 是将其快速、可复现地交付与隔离运行的标准方式。本文基于仓库 docker/README.md 与 docker/Dockerfile 的完整实现系统讲解 marimo 官方 Docker 镜像的三种形态marimo-slim、marimo-data、marimo-sql及其能力边界逐行剖析 Dockerfile 的构建细节非 root 用户、uv安装、端口与环境变量约定并给出可复制的本地构建、启动与访问步骤。读完本文你将掌握如何用一条命令把 marimo 编辑器跑在容器里并理解其端口、认证、教程文件与依赖注入的底层设计。一、marimo 官方镜像家族三种镜像的定位与差异仓库中的 docker/Dockerfile 采用多阶段multi-stage构建设计从同一个base基础镜像出发派生出三个可供直接使用的镜像目标对应文档 docker/README.md 中列出的三种镜像镜像目标继承关系额外安装内容典型用途basepython:3.13-slimmarimo 本体固定版本内部基础层不作为最终交付镜像marimo-slim直接继承base无最小镜像仅含 marimo 本体适合快速体验与最小化部署marimo-data继承basealtair、numpy、pandas及marimo[recommended,lsp]数据科学场景开箱支持数据分析与绘图marimo-sql继承datamarimo[sql]在前者基础上增加 SQL 单元格支持可直连 DuckDB 等数据库三个最终镜像的启动命令完全一致均执行marimo edit --no-token -p $PORT --host $HOST见 docker/Dockerfile 中slim、data、sql三个 target 的CMD区别只在于预装依赖的丰富程度。这意味着你可以在开发阶段使用功能最全的sql镜像在生产或资源受限环境切换到slim而无需修改任何启动逻辑。从源码结构看这三个 target 对应 Docker 构建时的--target参数docker build --target slim/data/sql仓库并未维护三个独立的 Dockerfile而是用一份文件管理整条镜像链。二、Dockerfile 逐层解析镜像内部究竟做了什么理解镜像内部结构才能安全、正确地使用它。以下是 docker/Dockerfile 的核心构建逻辑1. 基础镜像与标签LABEL# syntaxdocker/dockerfile:1.12 FROM python:3.13-slim AS base LABEL org.opencontainers.image.sourcehttps://github.com/marimo-team/marimo LABEL org.opencontainers.image.descriptionmarimo reactive notebook基础镜像是官方python:3.13-slimPython 版本锁定为 3.13镜像尽量精简通过 OCI 标准 LABEL 标注了源码仓库与镜像描述便于镜像仓库的元数据索引。2. 引入uv作为安装工具# Make uv and uvx available in the PATH for all target images COPY --fromghcr.io/astral-sh/uv:0.10.9 /uv /uvx /bin/镜像从ghcr.io/astral-sh/uv:0.10.9固定版本中直接拷贝uv与uvx可执行文件到/bin/使所有派生镜像都能使用 uv 完成 Python 包安装。uvx的存在还为容器内以uvx marimo方式运行工具提供了可能这一点与 marimo 自身的 Docker 集成逻辑一致见后文。3. 非 root 用户与工作目录RUN useradd -m appuser WORKDIR /app镜像创建了名为appuser的非 root 系统用户并在构建末尾通过USER appuser切换见各 target 定义。容器内以非 root 身份运行 marimo是面向生产部署的安全基线实践可避免容器逃逸类风险下以 root 权限直接操作宿主机。4. 固定 marimo 版本并注入环境变量ARG marimo_version0.12.8 LABEL org.opencontainers.image.version${marimo_version} ENV MARIMO_SKIP_UPDATE_CHECK1 ENV UV_SYSTEM_PYTHON1 ENV UV_COMPILE_BYTECODE1 ENV UV_LINK_MODEcopy RUN uv pip install --no-cache-dir marimo${marimo_version} \ mkdir -p /app/data \ chown -R appuser:appuser /app \ chown -R appuser:appuser /usr/local/lib/python3.13/site-packages/ \ chown -R appuser:appuser /usr/local/bin/这是镜像的核心安装步骤几个关键点值得展开版本可构建参数化ARG marimo_version0.12.8允许在构建时用--build-arg marimo_version版本号覆盖实现同一份 Dockerfile 构建任意 marimo 版本的镜像MARIMO_SKIP_UPDATE_CHECK1关闭 marimo 的版本更新检查避免容器每次启动时的网络探测与提示噪音保证容器行为确定UV_SYSTEM_PYTHON1让uv pip install直接安装到系统的 Python 环境而非创建独立虚拟环境这是容器场景的标准做法UV_COMPILE_BYTECODE1安装时预编译字节码加快容器冷启动时模块加载速度UV_LINK_MODEcopy采用复制而非硬链接的方式落盘文件兼容容器分层文件系统--no-cache-dir不保留 pip 下载缓存控制镜像体积安装后立即创建/app/data目录并将/app、Python site-packages 与/usr/local/bin的属主改为appuser保证非 root 用户有完整的读写权限。5. 内置教程目录COPY --chownappuser:appuser marimo/_tutorials tutorials RUN rm -rf tutorials/__init__.py镜像把仓库中的 marimo/_tutorials 目录含intro.py、dataflow.py、sql.py、ui.py、plots.py、fileformat.py、for_jupyter_users.py、external_dependencies.py、layout.py、markdown.py等示例笔记本复制到容器内/app/tutorials并删除__init__.py使其不再作为 Python 包导入只作为可打开的.py示例文件。这样首次进入容器即可在 marimo 文件浏览器中直接打开这些官方教程。6. 端口、监听地址与停止信号ENV PORT8080 EXPOSE $PORT ENV HOST0.0.0.0 STOPSIGNAL SIGTERM默认端口8080监听地址0.0.0.0允许从宿主机经端口映射访问两者均由环境变量驱动可运行时覆盖STOPSIGNAL SIGTERM确保docker stop时向 marimo 进程发送 SIGTERM实现优雅退出配合exec方式启动命令见下文 CMD信号可直达 marimo 主进程而非 shell。7. 三个 target 的启动命令# -slim entry point FROM base AS slim USER appuser CMD [sh, -c, exec marimo edit --no-token -p $PORT --host $HOST]data与sql的CMD与之相同。这里的要点exec前缀让marimo edit直接替换当前 shell 进程保证容器内 PID 1 就是 marimo 进程SIGTERM 能被正确接收处理--no-token关闭基于会话session的 token 认证。根据 marimo/_cli/cli.py 中token_message的定义默认情况下 marimo 会启用基于会话的认证并生成随机 token显式指定--no-token后不使用会话认证从而允许外部直接访问——这正是容器内无鉴权直连的开关-p $PORT与--host $HOST读取上述环境变量因此运行容器时可用-e PORT9000一键改端口。三、本地构建与运行从源码目录到可访问的 Notebook文档 docker/README.md 给出了完整的本地验证流程以下命令均在仓库根目录即包含docker/Dockerfile的目录执行# 构建镜像并打上 my_app 标签 docker build -t my_app . -f docker/Dockerfile # 启动容器把容器的 8080 端口映射到宿主机的 8080 端口 docker run -p 8080:8080 -it my_app # 浏览器访问 # http://localhost:8080构建指定形态的镜像默认构建会得到slim目标Dockerfile 中最后一个FROM。若要构建功能更完整的镜像使用--target显式指定# 构建含 pandas/numpy/altair 与 LSP 的数据科学镜像 docker build -t my_marimo_data . -f docker/Dockerfile --target data # 构建含 SQL 支持的镜像 docker build -t my_marimo_sql . -f docker/Dockerfile --target sql # 构建指定 marimo 版本的镜像 docker build -t my_marimo_custom . -f docker/Dockerfile \ --target data --build-arg marimo_version0.12.8使用不同的端口与绑定地址容器默认监听8080如需使用其他端口通过环境变量注入即可与 Dockerfile 中ENV PORT/ENV HOST的读取逻辑一一对应docker run -p 9000:9000 -e PORT9000 -it my_app此时访问http://localhost:9000。注意宿主机映射端口与容器内PORT需保持一致-p 9000:9000。挂载本地笔记本目录marimo 以.py文件存储笔记本详见 marimo/_tutorials 中的示例文件因此可以直接把宿主机上的笔记本目录挂载进容器实现容器内编辑、宿主机持久化# 将当前目录挂载到容器的 /app 下再启动 docker run -p 8080:8080 -v $(pwd):/app -it my_app之后在 marimo 文件浏览器中即可打开挂载目录下的.py笔记本所有修改实时写回宿主机文件。若同时还需要保留镜像内置的tutorials示例建议挂载到独立子目录而非覆盖整个/app。四、依赖矩阵recommended、lsp与sql到底装了什么data与sql镜像的差异源于 marimo 的 extras 依赖。这些依赖的真实定义位于 pyproject.toml 的[project.optional-dependencies]段落sql约 pyproject.toml 第 90-94 行duckdbSQL 单元格的执行引擎、polars[pyarrow]SQL 结果回流 Python、sqlglotSQL 单元格解析recommended约第 104-112 行聚合了marimo[sql]、marimo[sandbox]PEP 723 沙箱内核、cryptography持久化缓存清单的 Ed25519 签名、altair数据源查看器绘图、pydantic-ai-slim[openai]AI 功能、ruff格式化、nbformat导出 IPYNBlsp约第 114-117 行python-lsp-server与python-lsp-ruff为编辑器提供语言服务补全、诊断、格式化。由此可精确对应 Dockerfile 中的安装命令# -data 层数据科学 推荐依赖 LSP RUN uv pip install --no-cache-dir \ altair \ marimo[recommended,lsp] \ numpy \ pandas # -sql 层在 data 基础上叠加 SQL 支持 RUN uv pip install --no-cache-dir marimo[sql]即sql镜像实际拥有数据科学全家桶 SQL 推荐功能 LSP的最完整能力适合需要同时进行 DataFrame 分析与 SQL 查询的开发者。五、marimo 的 Docker 原生集成CLI 层面如何联动容器除了直接使用仓库中的 Dockerfilemarimo 本身也内置了把笔记本跑进容器的 CLI 能力相关实现位于 marimo/_cli/run_docker.pyrun_in_docker函数。它展示了两者在设计上的一致性可作为镜像用法的参照当通过marimo edit 远程URL --docker等方式触发时CLI 会先校验 Docker 是否安装、守护进程是否运行_check_docker_installed/_check_docker_running并检测目标端口是否已被其他容器占用随后以uvx marimo为入口拉起容器附加的参数同样包含--sandbox --no-token -p port --host 0.0.0.0见 marimo/_cli/run_docker.py 第 132-168 行并通过-e MARIMO_MANAGE_SCRIPT_METADATAtrue、-e MARIMO_IN_SECURE_ENVIRONMENTtrue注入安全环境变量它默认把端口设为8080与 Dockerfile 的ENV PORT8080一致容器启动后输出http://0.0.0.0:8080访问地址并实时流式打印容器日志。这说明仓库 Dockerfile 中的--no-token、--host 0.0.0.0、端口 8080 等约定与 marimo CLI 的容器化运行路径保持同构无论手工docker run还是通过 marimo 命令自动托管得到的都是一套统一的无 token、全接口监听、固定端口的运行模型。六、常见问题与使用建议访问被拒绝或需要 token确认启动命令包含--no-token。该参数的行为定义在 marimo/_cli/cli.py 的token_message中未指定时 marimo 会启用基于会话的认证并生成随机 token--no-token明确关闭它。默认CMD已带此参数但若你自行覆盖CMD或通过uvx marimo启动则需手动补上。容器内数据写不进去镜像以非 root 用户appuser运行工作目录/app及 Python 包目录已显式chown给该用户见 Dockerfile 第 22-26 行。若挂载宿主机目录请确保目录权限允许appuserUID 1000 左右写入否则可改用具名卷-v marimo_data:/app/data。如何在容器内运行已保存的笔记本而非编辑器默认CMD是marimo edit编辑器模式。如需以run模式执行可覆盖命令例如docker run -p 8080:8080 -v $(pwd):/app -it my_app marimo run /app/notebook.py --no-token -p 8080二者共用同一套端口与认证约定。体积敏感的场景选哪个slim仅含 marimo 本体是最小交付形态data与sql依次叠加数据科学与 SQL 依赖按实际需求选择避免无谓的镜像体积膨胀。总结marimo 的 Docker 支持采用单 Dockerfile、多构建目标的简洁设计base层用固定版本的uv以非 root 用户安装固定版本的 marimoslim/data/sql三个 target 按依赖梯度提供从最小到全功能的运行环境统一以marimo edit --no-token -p $PORT --host $HOST作为入口。配合 docker/README.md 的构建与运行命令你可以在几分钟内获得一个可复现、可移植、可挂载本地笔记本目录的 marimo 编辑环境而 marimo/_cli/run_docker.py 中 CLI 侧的容器集成则展示了 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考