Monday, July 1, 2013

nbconvert: PDF from iPython Notebook

UPDATE 2013-07-19: For details on the alternative to nbconvert briefly mentioned below, long custom PDF page sizes, see On Mac, only Firefox can PDF without page breaks.

UPDATE 2013-07-15: See Quick link to download nbconvert for updated download location.

The official iPython Notebook documentation states that to convert a notebook to PDF, you should use your browser's "Print to PDF" capability. The problem is that that chops charts and graphs in half due to PDF pagination (unless you are able to configure a custom PDF paper size e.g. 60 inches long).

A command-line utility, nbconvert, which will eventually be merged into IPython but is not yet, nicely converts Notebooks to PDF. It even includes nice instructions on installing on a Mac, but the instructions are only 98% complete. Below are the missing steps:

  1. Download the nbconvert package as a Zip and unzip to your home directory.
  2. Follow the steps from, specifically:
    1. pip install jinja2
    2. pip install markdown
    3. curl > docutils.tgz
    4. pip install -U docutils.tgz
    5. pip install pygments
    6. sudo easy_install -U sphinx
    7. Install PanDoc via the installer
    8. Install MacTex via the .pkg
  3. Execute to convert your .ipynb to .pdf:
    export PYTHONPATH=~/nbconvert-master/nbconvert/utils
    python ~/nbconvert-master/nbconvert1/ --format=pdf MyNotebook.ipynb


caoimhinp said...

Timely post.

I'm getting an error: No module named lexers.

Do you have any idea what might be the source of that (other than there is no module named lexers)?

Thanks for making the old source available. I need to export to other formats and deleting the old repo was unappreciated.

Michael Malak said...

The export PYTHONPATH=~/nbconvert-master/nbconvert/utils is supposed to take care of lexers since is in that directory. If the iPython 0.13 archival zip file expanded into a directory that is named differently than the non-unavailable 0.13 release zip file, you may need to adjust my suggested PYTHONPATH.

caoimhinp said...

What I downloaded didn't have the utils directory. I downloaded Carl Fischer's fork ( and the required file is in converters. That worked out for me.

Thanks for the quick reply.

Michael Malak said...

OK, glad you got it working. That's weird because I just now downloaded the archive I linked, and there is an nbconvert/utils/ in there. It's just that the parent directory has the SHA code instead of "master", making it

export PYTHONPATH=~/nbconvert-173bb08dd86d02a7485801969c94d4816913cd09/nbconvert/utils

caoimhinp said...

Actually, to be clear, the module is in the converters directory. It is referenced by the module. That file was missing from what I downloaded and I checked Brad Reisfeld's repo and it's missing from there as well. I don't know where it broke which is why I went back a bit farther and used someone else's fork.

caoimhinp said...

I had changed the name of the directory before using it anyway.

Thanks again though. You lead me to where I could get a working version. I was killing myself with the broken stuff in the current ipython repo.

rajin said...

I have tried to download nbconvert but the github page says it is now part of ipython package and it does not contain any code to download anymore. The issue is, even though my ipython is up to date (just did that) I dont have any nbconvert in it. Could you shed some light on that?

Michael Malak said...

Did you following the link from the July 15 update I posted at the top of this blog article? You can download the last version of nbconvert before it was deleted/moved from

Christian Fobel said...

You can also try the latest `nbconvert` by cloning the latest IPython from Github (see below). You can then install just the `notebook` part to use the latest `notebook` (include `nbconvert`) without upgrading your entire IPython instance.

So, first clone to a working directory somewhere:

git clone

Then, run the following to install just the new notebook:

pip install -e .[notebook]

The latest version of `nbconvert` includes some great features, including rendering Markdown notebook cells into Latex :D