## 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.

```text
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:

```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.