python nbconvert
## nbconvert：深入理解 Jupyter Notebook 转换工具
用过 Jupyter Notebook 的人都会遇到这样一个场景：你精心整理了一个分析报告，里面有代码、图表、说明文字，但当你想要把这份成果分享给别人时，发现对方电脑上没有装 Jupyter，或者对方只是想快速浏览最终结果，不想看中间的计算过程。
这时候就要用到 nbconvert 了。
nbconvert 是什么
nbconvert 是 Jupyter 生态中的一个核心工具，它专门负责把.ipynb格式的文件转换成其他格式。打个比方，可以把 Jupyter Notebook 想象成一个流程记录仪，它既记录了原材料（代码），也记录了加工过程（运行记录），还记录了最终成品（输出结果）。而 nbconvert 就是一台"再加工机器"，它能根据你的需求，把这些记录按照特定模板重新包装成不同的形式。
有意思的一点是，nbconvert 本身不依赖浏览器，也不需要用 Jupyter Notebook 服务。这意味着即使在没有图形界面的服务器上，也可以通过命令行完成转换任务。我曾经遇到过需要在远程服务器上批量生成报告的场景，nbconvert 很好地解决了这个问题。
nbconvert 能做什么
nbconvert 支持多种输出格式，每种格式都有其适用的场景：
HTML 格式是最常用的。把 Notebook 转成 HTML 后，可以直接在浏览器中查看，而且保留了代码的高亮显示、数学公式渲染（如果用了 MathJax）、以及图表的可视化效果。对于需要分享给团队内部审阅的场景特别方便。
PDF 格式适合正式报告或学术论文。不过这里有个坑 —— nbconvert 生成 PDF 有两套机制：一套是通过 LaTeX，另一套是通过 web 截图。LaTeX 路径生成的 PDF 质量更高，但需要安装 LaTeX 环境；web 截图路径则简单得多，但对复杂格式的支持有限。我的建议是，如果是正式场合的文档，宁可花点时间配好 LaTeX，输出效果会更专业。
Markdown 格式则适用于文档系统或版本控制。很多人在 Git 仓库里存储 Notebook 时，会同时用 nbconvert 生成 Markdown 版本，这样就能直接在 GitHub 上预览文档内容，不需要额外配置 Jupyter 渲染器。
reStructuredText 格式主要面向 Sphinx 文档系统。虽然 RST 用的人相对较少，但在 Python 开源项目的文档体系里还是经常见到。
此外还有 LaTeX、AsciiDoc 等格式，不过这些相对小众。
nbconvert 怎么使用
最基本的使用方式就是命令行：
# 把 notebook.ipynb 转换成 HTMLjupyter nbconvert--tohtml notebook.ipynb# 转换成 PDFjupyter nbconvert--topdf notebook.ipynb# 转换成 Markdownjupyter nbconvert--tomarkdown notebook.ipynb不过在实际工作中，这些基本用法往往不够用。
自定义模板：nbconvert 支持 Jinja2 模板系统，这意味着可以完全控制输出内容的样式和结构。比如说，需要生成带公司 Logo 的报告，可以写一个自定义模板：
# 在模板中可以控制哪些 cell 显示，哪些隐藏# 比如只显示 Markdown cell 和输出结果，隐藏代码 cell{%-forcellinnb.cells-%}{%-ifcell.cell_typein['markdown','code']-%}{%-ifcell.cell_type=='code'-%}# 只显示输出，不显示输入代码{%-foroutputincell.outputs-%}{{output.text|indent(4)ifoutput.output_type=='stream'else''}}{{output.data['text/plain']|indent(4)if'text/plain'inoutput.dataelse''}}{%-endfor-%}{%-else-%}{{cell.source}}{%-endif-%}{%-endif-%}{%-endfor-%}参数控制也很实用。比如想要在转换时执行 Notebook，可以加--execute参数；需要超时时间，用--ExecutePreprocessor.timeout=120。这里有个细节：--execute会在转换前重新执行整个 Notebook，这对于需要更新数据的场景特别有用。
最佳实践
在实际项目中使用 nbconvert，有几个踩过坑之后的经验值得一提：
批量处理时注意环境隔离。有一次我需要生成一百多份报告，每个 Notebook 依赖不同的包。最开始直接在同一个 Python 环境里跑，结果包冲突问题搞得一团糟。后来改用每个 Notebook 维护自己的虚拟环境，再通过--ExecutePreprocessor.kernel_name指定内核，才解决了这个问题。
输出目录结构要保持一致。可以写个简单的函数来封装转换逻辑：
importosfromnbconvertimportHTMLExporterfromnbformatimportreaddefconvert_notebook(notebook_path,output_dir):""" Convert notebook to HTML with consistent directory structure Args: notebook_path: Path to .ipynb file output_dir: Output directory for converted files """# 读取 notebookwithopen(notebook_path)asf:nb=read(f,as_version=4)# 配置导出器exporter=HTMLExporter()exporter.exclude_input=False# 是否包含代码exporter.exclude_output_prompt=True# 执行转换body,resources=exporter.from_notebook_node(nb)# 保存结果output_file=os.path.join(output_dir,os.path.basename(notebook_path).replace('.ipynb','.html'))withopen(output_file,'w',encoding='utf-8')asf:f.write(body)returnoutput_file处理大文件时注意内存。如果 Notebook 里有大量图片或大数据框的输出，直接转 PDF 很容易卡死。一个可行的策略是先用--to html转成 HTML，再通过系统命令把 HTML 转成 PDF。虽然多了一步，但稳定得多。
和同类技术对比
这方面常用来对比的工具是 Papermill 和 Voilà。
Papermill专注于参数化执行 Notebook，它的设计哲学是把 Notebook 当作模板，通过传入参数来批量生成结果。nbconvert 则更侧重于格式转换。两者可以配合使用：Papermill 先准备好计算好的 Notebook，nbconvert 再转换成适合分发的格式。
Voilà则是把 Notebook 转成交互式 Web 应用，适合构建数据仪表盘。相比之下，nbconvert 的输出是静态的，没有交互能力。但如果只是做报告分享，静态文档反而更合适 —— 不需要维护后端服务，直接用浏览器就能打开，对接收方来说几乎零使用成本。
还有一个工具叫Quarto，它其实是 R Markdown 在 Python 生态的对应物，支持更多的输出格式和更复杂的文档结构。但 Quarto 需要学习一套新的语法，对于已经在用 Jupyter Notebook 的团队来说，nbconvert 的学习成本低得多。
我个人倾向于这样选择：如果团队成员都熟悉 Jupyter Notebook，且需求主要集中在报告生成和格式转换，用 nbconvert 就够了。如果需要参数化批量处理，加上 Papermill。只有到了需要写完整的技术文档或书籍时，才考虑切换到 Quarto 这类更重量级的工具。
回到最开始的问题，nbconvert 其实解决了一个很实际的需求：让 Jupyter Notebook 里产出的成果能够被更广泛地使用。无论是在团队内分享分析报告，还是生成正式的交付文档，又或者是把分析过程整理成博客文章，都能用 nbconvert 来完成。这个工具虽然简单，但在日常工作中确实省了不少事。