Diagnose and fix nbconvert export failures (PDF, HTML, execution)

[{"constraint": ">=6.0; PDF export additionally requires pandoc >=2.9.2,<4.0.0 and a TeX distribution providing xelatex", "technology": "nbconvert", "version_scheme": "semver"}]

Diagnose and fix nbconvert export failures

Use this when jupyter nbconvert --to pdf notebook.ipynb (or html, markdown, slides) fails, or when File > Download as errors with nbconvert failed. An export is two separate stages — executing the notebook, then converting the result — and each stage fails differently. Classify from the first error line, then fix that stage.

1. Classify: execution failure vs conversion failure

Run the export from the command line (not just the UI) so you see the full traceback, and read the first distinctive error:

A. CellExecutionError, or Timeout waiting for execute reply: the notebook itself fails to run. Fix the notebook first (step 2). Note: nbconvert does not execute by default — this failure only appears with --execute.

B. PandocMissing: "Pandoc wasn't found. ...": pandoc is missing or too old. nbconvert needs pandoc >= 2.9.2 and < 4.0.0.

C. OSError: "xelatex not found on PATH, if you have not installed xelatex you may need to do so. ...": PDF export needs a TeX distribution. Install one (step 3).

D. PDF creating failed, captured latex output: ... / Failed to run "..." command:: xelatex ran but the LaTeX compile failed. The captured output holds the real error — usually a missing LaTeX package or a LaTeX error from notebook content (step 4).

2. Execution failures: make the notebook run clean first

Reproduce the execution stage on its own:

jupyter nbconvert --to notebook --execute notebook.ipynb

• Timeout waiting for execute reply (30s): c.ExecutePreprocessor.timeout defaults to 30 seconds per cell. Long-running cells die at this limit; raise it in config or split the cell.

• Cells that legitimately raise: pass --allow-errors to keep executing and export the tracebacks.

• Rule out hidden state before blaming nbconvert: open the notebook and do Restart & Run All. A notebook that only works because of out-of-order cell execution will fail under nbconvert's clean top-to-bottom run.

3. Missing tools: pandoc and TeX

pandoc --version   # need >= 2.9.2, < 4.0.0
which xelatex

Install a TeX distribution (Debian/Ubuntu; see the nbconvert install docs for other platforms):

sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic

If xelatex is installed but nbconvert can't find it — common when exporting from the UI, whose server process has a different PATH than your shell — point nbconvert at it directly with the c.PDFExporter.latex_command config key (step 4).

4. LaTeX compile fails: read the captured output

The PDF creating failed, captured latex output text is the xelatex log. Read it for the actual error: most often a missing LaTeX package (install it with tlmgr, apt, or the MiKTeX console) or a LaTeX error triggered by notebook content such as unescaped special characters. To iterate faster than full PDF runs, export to LaTeX only and compile by hand:

jupyter nbconvert --to latex notebook.ipynb
xelatex notebook.tex

PDF export config keys (all settable in jupyter_nbconvert_config.py):

• c.PDFExporter.latex_command — default ["xelatex", "{filename}", "-quiet"]; override with an absolute path if xelatex is not on the server's PATH.

• c.PDFExporter.latex_count — how many times xelatex runs (default 3).
• c.PDFExporter.verbose — show the latex command output instead of capturing it.
• c.PDFExporter.texinputs — extra TEXINPUTS directory for local style files.

5. Useful non-PDF exports

jupyter nbconvert --to html --no-input notebook.ipynb   # hide code cells
jupyter nbconvert --to html --template lab notebook.ipynb
jupyter nbconvert --to markdown notebook.ipynb
jupyter nbconvert --to slides notebook.ipynb --post serve

--stdout pipes the output instead of writing a file.

6. Checklist for the failing export

1. Reproduce from the CLI to get the full traceback, not just the UI's nbconvert failed summary.

2. Classify: CellExecutionError/timeout vs PandocMissing vs xelatex-not-found vs LaTeX compile failure.

3. Execution: fix the notebook, use --allow-errors, or raise ExecutePreprocessor.timeout.

4. Tools: pandoc >= 2.9.2; texlive-xetex plus recommended fonts.

5. LaTeX: read the captured output; export --to latex and compile manually to iterate.

6. UI-only failures: compare PATH and config between your shell and the notebook server process.

Built from the nbconvert source (PDFExporter error strings for xelatex-not-found and LaTeX compile failure, PandocMissing version bounds, ExecutePreprocessor timeout default) and recurring Jupyter Discourse threads on PDF-via-LaTeX export failures.