Skip the hassle. Use our online tool for one-click Jupyter to PDF conversion.

Converting Jupyter notebooks to PDF can be incredibly useful for sharing analyses with people who don’t have Jupyter installed. However, setting up the necessary dependencies can be a bit tricky. There are multiple options available for this conversion process, each with its own set of advantages and disadvantages. In this post, we’ll specifically review two popular methods: nbconvert and Quarto. We’ll explore the setup process, features, and limitations of each approach, helping you choose the best method for converting your Jupyter notebooks to PDF.

nbconvert

nbconvert is the official library from the Jupyter team, designed to convert Jupyter notebooks into various formats. It offers flexibility in the conversion process, allowing users to generate PDFs through two distinct methods: webpdf or xetex. This versatility makes nbconvert a powerful tool for transforming Jupyter notebooks into easily shareable PDF documents.

nbconvert WebPDF

Use our online tool to try nbconvert WebPDF.

nbconvert-webpdf

The WebPDF option in nbconvert converts Jupyter notebooks to PDF using web technologies. Key points:

  1. Easy Setup: Fewer dependencies than LaTeX-based conversion.
  2. Browser-based Rendering: Uses headless browser for accurate output.
  3. JavaScript Support: Can render elements that require JavaScript, such as Plotly plots. However, note that while these elements will be visible in the PDF, they won’t be interactive. For example, a Plotly chart will appear as a static image in the final PDF.
  4. Consistent Styling: Maintains notebook interface styling.
  5. Potential Limitations: May struggle with very complex layouts.

Here’s how to use nbconvert with the WebPDF option:

# install nbconvert + other dependencies
pip install "nbconvert[webpdf]"
playwright install-deps
playwright install chromium

# convert to pdf using webpdf
jupyter nbconvert mynotebook.ipynb --to webpdf

You can hide the code via the --no-input option.

jupyter nbconvert mynotebook.ipynb --to webpdf --no-input

Use our online tool to try nbconvert WebPDF with hidden code.

One caveat of this approach is that local images embedded via paths (e.g. ![myimage](/images/blog/jupyter-notebook-convert/path/to/image.png)) don’t work.

nbconvert PDF

Use our online tool to try nbconvert PDF.

nbconvert-pdf

The PDF option in nbconvert uses a LaTeX-based conversion process. Key points include:

  1. High-quality output: Especially suitable for documents with complex mathematical content.
  2. Two-step conversion: Converts the notebook to LaTeX first, then to PDF.
  3. Customization potential: Allows for fine-tuning through LaTeX templates.
  4. Dependency requirements: Needs pandoc and XeTeX, which can be challenging to install and configure.
  5. Installation complexity: Setup process may vary across different operating systems, posing difficulties for users unfamiliar with LaTeX environments.
  6. Professional results: Produces polished documents, but at the cost of a more complex setup process.

Here’s how to use nbconvert with the PDF option:

# install nbconvert
pip install nbconvert

# you must install pandoc and xetex before using it!

# convert to pdf using webpdf
jupyter nbconvert mynotebook.ipynb --to pdf

You can hide the code via the --no-input option.

jupyter nbconvert mynotebook.ipynb --to pdf --no-input

Use our online tool to try nbconvert PDF with hidden code.

Note: If you’re embedding external images, ensure all the paths are correct otherwise this method will fail.

Quarto

quarto

Quarto is a newer project that offers notebook-to-PDF conversion among its features. Key points include:

  1. Comprehensive tool: Quarto provides a powerful and flexible conversion process, offering robust features and high-quality output.
  2. Dependency requirements: Installation of Quarto, Pandoc, and XeTeX is necessary, which can be challenging for users unfamiliar with system-level installations.
  3. Installation complexity: The setup process may vary across different operating systems, potentially making it difficult to ensure all components work together smoothly.
  4. Learning curve: While potentially complex to set up, Quarto’s capabilities make it a compelling option for those willing to invest time in learning the tool.
  5. JavaScript limitations: Since Quarto uses XeTeX for PDF generation, JavaScript-based interactive elements in notebooks won’t be functional in the resulting PDF. This may affect the representation of certain dynamic visualizations (e.g. Plotly) or interactive widgets.

Once you installed Quarto and XeTeX, run:

quarto render mynotebook.ipynb --to pdf

Note: If you’re embedding external images, ensure all the paths are correct otherwise this method will fail.

Quarto customization

quarto-custom

Quarto offers a wide range of customizations. To utilize these, you need to add a raw cell to your notebook and set the configuration there. For example, you can generate a table of contents (TOC) with clickable links and number sections based on markdown headers. The following example demonstrates how to set up these features:

---
title: "My document"
format:
  pdf:
    toc: true
    number-sections: true
    colorlinks: true
---

To give you a glimpse of how powerful Quarto is, let’s look at the following configuration:

---
title: "My Document"
format: 
  pdf: 
    documentclass: report
    classoption: [twocolumn, landscape]
    lof: true
    lot: true
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    colorlinks: true
---

This configuration will create a PDF document with a specific layout and structure. It sets the document class to report and applies a two-column landscape layout. The document will include a List of Figures (lof) and a List of Tables (lot). The geometry settings adjust the page margins, with a 30mm top margin and 20mm left margin, and ensures the text height is rounded to whole lines. The colorlinks option makes hyperlinks in the document appear in color.

If you want to learn more, check out Quarto’s PDF basics guide and the full Quarto PDF reference.

Which one to use?

After exploring these options for converting Jupyter notebooks to PDF, here’s my recommendation on which one to use:

  1. If you’re new to this or need a quick solution: Start with nbconvert using the webpdf option. It’s the easiest to set up and use, especially if you’re already familiar with Jupyter. Just remember that it might struggle with more complex notebooks.

  2. If you’re comfortable with some system installations and need better LaTeX support: Go for nbconvert with XeTeX. It’s more robust than the webpdf option and handles LaTeX content well. You’ll need to install a few extra things like pandoc and XeTeX, but it’s worth it for the improved output quality.

  3. If you’re an advanced user or have complex document needs: I’d recommend giving Quarto a try. Yes, it has a steeper learning curve and a more complex setup, but the power and flexibility it offers are unmatched. If you’re willing to invest some time in learning it, Quarto can handle pretty much anything you throw at it.

In my experience, I’ve found that most users start with nbconvert (webpdf), then move to nbconvert with XeTeX as their needs grow. Quarto is fantastic, but it’s overkill for simple conversions.

Remember, there’s no one-size-fits-all solution. Consider your technical comfort level, the complexity of your notebooks, and how much customization you need in your PDFs. Don’t be afraid to experiment with different options to find what works best for you.

Personally, I use nbconvert with XeTeX for most of my work, but I’m increasingly turning to Quarto for more complex projects. It’s all about finding the right tool for your specific needs.