← All guides

Fix: nbconvert failed because xelatex was not found on PATH

If jupyter nbconvert --to pdf notebook.ipynb stops with xelatex not found on PATH, the notebook converted fine, the PDF step failed because there is no LaTeX engine installed. You have three ways out: install a TeX distribution (heaviest, best print fidelity), switch to --to webpdf which renders through headless Chromium instead of LaTeX (no TeX install, but needs a browser download), or skip the local toolchain entirely and render the notebook to PDF in your browser with PDFMoka's ipynb to PDF converter. Pick based on what you actually need below.

Why this happens

--to pdf is a two-stage pipeline. nbconvert first turns your .ipynb into a .tex file, then hands that .tex to XeLaTeX to typeset the actual PDF. The first stage almost always succeeds, which is why you often see the .tex (or a notebook.tex line in the log) get written right before the crash. The failure is the second stage: nbconvert calls out to the xelatex binary, cannot find it on your system PATH, and aborts.

A typical traceback looks like this (paths abbreviated):

[NbConvertApp] Converting notebook Untitled.ipynb to pdf
[NbConvertApp] Writing 20652 bytes to notebook.tex
[NbConvertApp] Building PDF
...
OSError: xelatex not found on PATH, if you have not installed xelatex you may
need to do so. Find further instructions at
https://nbconvert.readthedocs.io/en/latest/install.html#installing-tex.

verify against current docs / your machine: the exact wording of the error string has shifted slightly across nbconvert versions (some emit nbconvert failed: xelatex not found on PATH, some Error: xelatex not found in path, older ones raise OSError). Run your own failing command and paste the real line before publishing; the traceback frames and byte count above are illustrative, not from your environment.

Since nbconvert 5.0, the engine is specifically XeTeX/XeLaTeX (not the older pdfTeX), because XeTeX can pull fonts from your operating system and handles Unicode and OpenType fonts better. So installing "some LaTeX" is not enough, you need a distribution that provides the xelatex command.

Route 1: Install a TeX distribution (keeps --to pdf working)

Choose this if you specifically need the LaTeX-rendered look, or your workflow already depends on --to pdf.

macOS (MacTeX, large; or the smaller BasicTeX):

brew install --cask mactex-no-gui
# smaller alternative:
# brew install --cask basictex

Debian / Ubuntu:

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

Windows: install MiKTeX or TeX Live from their official installers.

nbconvert also needs Pandoc for the notebook-to-LaTeX stage:

# macOS
brew install pandoc
# Debian/Ubuntu
sudo apt-get install pandoc

After installing, open a new terminal (so the updated PATH is picked up) and confirm the binary is visible:

xelatex --version

If that prints a version, re-run your conversion:

jupyter nbconvert --to pdf notebook.ipynb

A very common gotcha, worth calling out: on Windows especially, people install MiKTeX but the error persists because the MiKTeX bin directory was never added to PATH, or the terminal/Jupyter session was started before the install and still holds the old PATH. If xelatex --version fails in the same shell where nbconvert fails, the problem is PATH, not a missing install. Restart the terminal (and the Jupyter kernel/server) and re-check.

Route 2: Use --to webpdf (no LaTeX at all)

If you do not want a multi-gigabyte TeX install, nbconvert can render through headless Chromium instead. This path converts the notebook to HTML, renders that HTML in Chromium, and prints it to PDF, so it never touches xelatex.

pip install "nbconvert[webpdf]"
jupyter nbconvert --to webpdf notebook.ipynb

The [webpdf] extra pulls in Playwright, which drives Chromium. If Playwright cannot find a suitable Chromium build, you will hit a second error like No suitable chromium executable found on the system. Fix it by letting it download one, or installing the browser explicitly:

# option A: allow the download inline
jupyter nbconvert --to webpdf --allow-chromium-download notebook.ipynb

# option B: install the browser once, up front
playwright install chromium

verify against current docs: the [webpdf] extra and the --allow-chromium-download flag are current in nbconvert 7.x. If you are on an older 6.x line, confirm the flag name against jupyter nbconvert --help before relying on it.

Trade-off to be honest about: webpdf output looks like the HTML/browser render of your notebook (close to the JupyterLab view), not the LaTeX-typeset look. For most people sharing a notebook that is fine or even preferable; if you specifically wanted the academic LaTeX styling, use Route 1.

Route 3: Render in the browser, skip the toolchain (fastest)

If this is a one-off, or you just need a clean PDF to hand in or share and do not want to install TeX, Pandoc, or Chromium at all, convert the notebook directly in your browser with the PDFMoka ipynb to PDF converter. It renders code cells with syntax highlighting, keeps matplotlib and image outputs, and typesets math, with no LaTeX dependency. Because the conversion runs entirely client-side, the notebook never leaves your device, which matters if the notebook contains internal data or credentials in cell output.

This is the right call when the blocker is purely "I don't have a working local toolchain and don't want to build one." It is not a fit if you need a scripted/CI conversion baked into an automated pipeline, that is what Route 1 or Route 2 on your own machine is for.

Which route should you pick?

  • You need the LaTeX academic look, or already script --to pdf: Route 1 (install XeLaTeX + Pandoc).
  • You want a local, no-LaTeX conversion, and don't mind a Chromium download: Route 2 (--to webpdf).
  • You just want the PDF now, no installs, and privacy matters: Route 3, convert the .ipynb in your browser.

References