papermill：让 Jupyter Notebook 真正跑起来的工具

papermill：让 Jupyter Notebook 真正跑起来的工具

papermill 是一个专门解决 Jupyter Notebook 执行和复用问题的工具，目前在 GitHub 上有 6,448 个 Star。它的核心能力围绕两件事展开：给 notebook 注入参数，以及批量执行 notebook。

做数据分析的人对 Jupyter Notebook 都不陌生。写分析脚本、做可视化、记录实验过程，notebook 确实好用。但问题是，写好的 notebook 怎么复用？同一个分析模板，换成另一份数据，难道要手动改每个变量再跑一遍？

papermill 就是来解决这个问题的。

核心功能：参数化与执行

papermill 的使用逻辑很清晰。先在 notebook 里标记一个 parameters 单元格，里面写好默认参数。然后用 papermill 执行时，传入新的参数值，工具会自动把新值注入到一个 injected-parameters 单元格里，覆盖默认值。

Python API 的调用方式很直接：

import papermill as pm

pm.execute_notebook(
   'input.ipynb',
   'output.ipynb',
   parameters = dict(alpha=0.6, ratio=0.1)
)

命令行同样支持参数传入：

papermill input.ipynb output.ipynb -p alpha 0.6 -p ratio 0.1

参数的来源也很灵活。除了直接传键值对，还可以从 YAML 文件读取，或者传 base64 编码的 YAML 字符串。重复执行同一个 notebook 时，papermill 会自动替换上一次注入的参数单元格，而不是不断追加。

实际应用场景

这个工具在什么情况下有用？

第一种情况是做周期性报告。你有一份财务分析 notebook，每个月初要跑一遍，只是数据路径和日期参数不同。用 papermill 可以直接把参数化之后的 notebook 丢进定时任务里，不用每个月手动改代码。

第二种情况是构建 notebook 工作流。前一个 notebook 跑完，根据输出结果决定下一个 notebook 执行哪个。这在数据管道里很常见，papermill 把这种流程从手动复制粘贴变成了程序调用。

第三种情况是在大规模数据管道中使用 notebook。nteract 团队本身是 notebook 生态的活跃参与者，他们在构建数据流水线时积累了大量经验，papermill 的设计也带有这方面的倾向性。

存储后端支持

执行结果的输出路径支持多种协议：

• 本地文件系统
• HTTP/HTTPS
• AWS S3
• Azure DataLake / Blob Storage
• Google Cloud Storage

这意味着 notebook 输入可以放在 S3 上，执行结果也可以直接写回云端存储，不用先把文件拉到本地再处理。pip 安装时可以额外选择对应的 IO 依赖包，也可以一次装全。

一点看法

papermill 不是那种让人眼前一亮的炫技型项目，但它解决了一个很实际的问题：把 notebook 从单纯的交互式探索工具变成可复用的生产组件。很多数据团队都在 notebook 里做实验，实验完了想上线，要么重写一遍成 Python 脚本，要么就得手动操作。papermill 给出了另一种选择：保留 notebook 的优势，同时赋予它参数化和批量执行的能力。

它的设计有明确的倾向性，是在规模化使用 notebook 的数据管道中沉淀出来的经验。代码风格遵循 black 规范，CI 持续集成覆盖完善，文档托管在 ReadTheDocs 上。目前支持 Python 3.10 及以上版本。

如果你已经在用 Jupyter Notebook 做数据分析，并且开始面临复用和自动化执行的需求，可以看看这个工具。