# 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:
```bash
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
```bash
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):
```bash
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:
```bash
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
```bash
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.