Jupyter导出.ipynb为PDF时nbconvert报找不到chromium错误

报错提示：nbconvert failed: No suitable chromium executable found on the system. Please use '--allow-chromium-download' to allow downloading one.
触发原因：高版本nbconvert默认的WebPDF导出模式依赖Chromium内核做页面渲染，系统内无可用Chromium执行文件时就会抛出该错误。

方案1：开启自动下载适配版Chromium（操作成本最低） #

根据你触发导出的场景选对应操作即可：

• 图形界面点导出按钮触发报错：先关闭当前运行的Jupyter服务，在启动Jupyter的终端中先配置环境变量，再重启服务：
  • Windows（CMD终端）执行：

    set JUPYTER_NBCONVERT_ALLOW_CHROMIUM_DOWNLOAD=1
    jupyter notebook
    

  • Mac/Linux（Bash/Zsh终端）执行：

    export JUPYTER_NBCONVERT_ALLOW_CHROMIUM_DOWNLOAD=1
    jupyter notebook
    

  重启后第一次导出PDF时，程序会自动下载适配版本的Chromium，下载完成后即可正常导出，后续使用无需重复配置环境变量。
• 命令行调用nbconvert直接转文件：直接在转换命令中加允许下载参数即可：

  jupyter nbconvert --to webpdf --allow-chromium-download 目标文件.ipynb
  

方案2：复用本地已安装的Chromium内核浏览器（无需额外下载，适合网络受限场景） #

本地如果已经安装Chrome、Edge、Chromium任意一款Chromium内核的浏览器，无需重复下载组件，直接给nbconvert指定浏览器执行路径即可：

1. 先确认本地浏览器的执行文件完整路径，常见默认路径参考：
   • Windows：Chrome默认路径为C:\Program Files\Google\Chrome\Application\chrome.exe，Edge默认路径为C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
   • Mac：Chrome默认路径为/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
   • Linux：Chrome默认路径为/usr/bin/google-chrome
2. 如果之前没有生成过nbconvert配置文件，终端执行以下命令生成：

   jupyter nbconvert --generate-config
   

3. 打开用户目录下.jupyter/jupyter_nbconvert_config.py配置文件，添加/修改如下配置项，将路径替换为你本地查到的浏览器执行文件路径：

   c.WebPDFExporter.chromium_path = r"本地浏览器执行文件完整路径"
   

   注意：Windows系统路径前加r是为了避免反斜杠转义导致路径识别失败，保存配置后重启Jupyter服务，即可正常导出PDF。

方案3：切换为LaTeX导出通道（完全不依赖Chromium） #

如果不需要WebPDF的网页渲染效果，可以安装完整LaTeX环境后，切换为传统LaTeX模式导出PDF，整个流程不需要Chromium组件：

• 先安装对应系统的TeX发行版：Windows装MiKTeX、Mac装MacTeX、Linux装texlive-full
• 转换时指定导出类型为latex对应的pdf模式即可：

  jupyter nbconvert --to pdf 目标文件.ipynb
  

常见排查注意点 #

• 开启自动下载后如果下载失败，优先检查当前终端的网络连通性，Chromium自动下载受网络代理、防火墙限制时很容易超时失败，这种情况直接换方案2即可。
• 如果是在Python虚拟环境/Conda环境中安装的Jupyter，所有命令执行、环境变量配置、配置文件修改都要在对应环境下操作，避免配置不生效。
• 不要混用不同环境安装的nbconvert，比如系统全局装了低版本nbconvert，虚拟环境装了高版本，调用时可能因为路径优先级问题触发意料外的报错。

内容的提问来源于stack exchange，提问作者Girish Shenoy