10 Common Mistakes When Converting IPYNB to PDF (and How to Fix Them)

After helping thousands of users convert Jupyter Notebooks to PDF, the same ten mistakes come up over and over. Most of them have trivial fixes once you know what's happening. Here's the list, ranked roughly by how often we see them.

Mistake 1 — Exporting Without Running All Cells

Symptom: The PDF has code but no outputs, charts, or tables.

Cause: You restarted the kernel (or opened a notebook fresh from Git) and exported without re-executing. The outputs live in the .ipynb only if the cells were run in the current session.

Fix: Always run Kernel → Restart & Run All before exporting. Or, if you're using nbconvert, add --execute:

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

Mistake 2 — Clipped Wide DataFrames

Symptom: Your 30-column pandas DataFrame is cut off at column 8 in the PDF.

Cause: PDFs have a fixed page width. Most converters don't auto-scale wide tables.

Fix: Trim or transpose the DataFrame before exporting:

# Show only the first 10 columns
df.iloc[:, :10]

# Or transpose if the table is short
df.describe().T

For HTML-based conversion, wrap the table in a scrollable container — but most PDF converters will still clip it. The reliable fix is to limit columns.

Mistake 3 — Pixelated Matplotlib Charts

Symptom: Charts look fuzzy, especially when printed or zoomed.

Cause: Default matplotlib DPI is 100, which is fine for screen but looks bad in print.

Fix: Bump DPI in the first cell:

import matplotlib.pyplot as plt
plt.rcParams.update({
    "figure.dpi": 150,
    "savefig.dpi": 300,
    "font.size": 14,
})

For figures you save explicitly, use SVG (vector) instead of PNG:

plt.savefig("chart.svg", bbox_inches="tight")

Mistake 4 — Missing LaTeX Math

Symptom: Your beautifully typeset equations show up as raw $E = mc^2$ text.

Cause: Your converter doesn't support KaTeX/MathJax, OR your math delimiters are malformed.

Fix: First, check that your delimiters are paired. Inline: $E = mc^2$ . Display: $$\int_0^1 x^2 dx$$. Then verify the converter supports math rendering — ipynbtopdf.org and modern nbconvert do; older tools may not.

Escape stray dollar signs in prose: \$5 instead of $5.

Mistake 5 — Plotly Widgets That Disappear

Symptom: Your interactive plotly figure is completely absent from the PDF.

Cause: Plotly outputs are JavaScript widgets. PDFs don't run JavaScript.

Fix: Convert plotly to a static image before exporting:

import plotly.io as pio
pio.write_image(fig, "plot.png", width=1200, height=600, scale=2)

You'll need pip install kaleido. Then reference the PNG in a markdown cell.

Mistake 6 — Using the Wrong LaTeX Engine

Symptom: UnicodeEncodeError or missing character errors when your notebook contains emoji, CJK text, or smart quotes.

Cause: The default pdflatex engine can't handle Unicode.

Fix: Force nbconvert to use xelatex:

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

Or switch to the webpdf exporter, which uses Chromium and handles Unicode natively:

jupyter nbconvert --to webpdf notebook.ipynb

Mistake 7 — Giant File Sizes

Symptom: A 50 MB PDF that no one wants to download.

Cause: Your notebook has many high-resolution embedded base64 images, plus all the JSON overhead.

Fix:

Reduce matplotlib DPI to 150 (not 300) for screen-oriented PDFs.
Avoid %matplotlib widget outputs — they embed extra data.
Clear outputs you don't need: jupyter nbconvert --clear-output.
Use JPG instead of PNG for photographic images in markdown cells.

Mistake 8 — Inconsistent Code Highlighting

Symptom: Some code blocks have syntax highlighting, others don't.

Cause: Mixed cell types or inconsistent markdown code fences.

Fix:

In markdown cells, always use triple-backtick fences with a language: ```python not just ```.
In code cells, make sure the cell type is actually "Code" not "Raw".
For nbconvert LaTeX output, install python-markdown-math or switch to webpdf for consistent highlighting.

Mistake 9 — Bad Page Breaks

Symptom: A chart gets split across two pages, or a heading appears at the bottom of a page with its content on the next.

Cause: PDF converters don't know which blocks "belong together."

Fix:

For nbconvert LaTeX output, insert a page break before major sections:

from IPython.display import Markdown
Markdown(r'\newpage')

For HTML/webpdf output, use CSS:

<style>
  h1, h2 { page-break-before: auto; page-break-after: avoid; }
  img, svg { page-break-inside: avoid; }
</style>

For online converters like ipynbtopdf.org, page breaks are handled automatically — they avoid splitting figures and tables across pages.

Mistake 10 — No Headings or Structure

Symptom: A 20-page PDF that's a wall of text with no navigation.

Cause: You didn't use markdown headings (#, ##, ###).

Fix: Structure your notebook with markdown cells:

# Introduction

## Data Loading

## Analysis

### Subsection: Correlation

## Results

## Conclusion

nbconvert (LaTeX mode) and ipynbtopdf.org will both generate a clickable table of contents from these headings.

Bonus Mistake — Not Testing the PDF Before Sharing

Symptom: You send the PDF to your boss, then realize cell 12 has a typo.

Fix: Always open the PDF and skim it before sharing. Don't trust that the conversion was perfect. The 30 seconds you spend reviewing will save you from embarrassment.

The Pre-Export Checklist

Run through this before every export:

Kernel → Restart & Run All executed
Wide DataFrames trimmed to ~10 columns
matplotlib DPI at 150+, font size 14+
Plotly figures converted to PNG
LaTeX delimiters paired and escaped
Using xelatex or webpdf for Unicode
File size reasonable (< 10 MB)
Markdown headings give the notebook structure
Skimmed the PDF before sharing

Conclusion

Every mistake on this list has a 30-second fix once you recognize it. The problem is that most people only discover them after producing a broken PDF and having to redo the conversion. Internalize the checklist above, run through it before each export, and your IPYNB to PDF conversions will be clean on the first try — every time.