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

TL;DR

For "nbconvert failed": run the export from the command line (not just the UI) so you see the full traceback, and read the first distinctive error: A.

nbconvert failed

When to use

You are seeing this: An export is two separate stages, executing the notebook, then converting the result, and each stage fails differently. Use this skill when you run into "Diagnose and fix nbconvert export failures (PDF, HTML, execution)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

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.