Fixing nbconvert LaTeX Errors for Good

If you've ever run jupyter nbconvert --to pdf and been greeted with a wall of red text, you're not alone. The vast majority of nbconvert failures trace back to a handful of LaTeX and pandoc issues. Here's how to fix each one.

1. xelatex: command not found

This is the single most common error. nbconvert relies on a TeX distribution to render the final PDF, and it isn't installed by default.

Fix — install a TeX distribution:

• macOS: brew install --cask mactex-no-gui (smaller than full MacTeX)
• Ubuntu/Debian: sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic
• Windows: Install MiKTeX

After installing, restart your terminal and run xelatex --version to confirm.

2. Pandoc Conversion Failures

nbconvert uses pandoc to convert markdown cells. If pandoc is missing or outdated, conversion fails midway.

# Check version (should be >= 2.0)
pandoc --version

# Install / upgrade
brew install pandoc       # macOS
sudo apt-get install pandoc  # Linux

3. UnicodeEncodeError on Non-ASCII Characters

If your notebook contains emoji, CJK characters, or smart quotes, the default LaTeX engine can choke.

Fix: force nbconvert to use xelatex, which handles Unicode properly:

jupyter nbconvert --to pdf --PDFExporter.latex_command='xelatex {filename} -quiet' notebook.ipynb

Or pin it in your jupyter_nbconvert_config.py:

c.PDFExporter.latex_command = "xelatex {filename} -quiet"

4. Missing or Broken matplotlib Charts

Charts disappear when nbconvert executes your notebook but the backend isn't set correctly.

Add this to the first cell of your notebook:

import matplotlib
matplotlib.use("agg")  # non-interactive backend
import matplotlib.pyplot as plt
%matplotlib inline

Then export with --execute so outputs are regenerated:

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

5. The Pragmatic Alternative

If you've spent more than 15 minutes fighting the errors above, consider an online converter. Tools like ipynbtopdf.org handle the rendering server-side — no LaTeX, no pandoc, no Python environment — and typically return a clean PDF in under 5 seconds.

Summary

Fix these once and your local nbconvert workflow will be reliable — or skip the setup entirely with an online tool.