Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

code A guest post by Jonathan Frederic who is currently working as a full time IPython Developer. He works on the IPython Notebook and related tools, and enjoys spending his spare time writing a video game in Python. He can be contacted either by email at or on GitHub at

In my last post covering the IPython Notebook, I showed you how to get started. In this post I will show you how to write plugins for both the IPython Notebook and nbconvert. The plugins will work together, enabling you to interactively exclude cells in exported notebooks. To do this, you will write two plugins. The first plugin will allow you to select which cells to exclude. The second plugin will exclude the cells during export of the notebook.

This post was written and tested on Lubuntu 13.10 and assumes that you have read the getting started post.

Notebook Plugin

To start with, a GUI is required that allows you to select what cells should be excluded. The IPython Notebook’s GUI can be extended with custom features to allow you to do this. A notebook plugin has the ability to register custom toolbars.

Loading Custom Notebook Code

To add custom content to the notebook server, you need to create an IPython user profile. Do this by running:

Note: If you have Python 3.x installed on your machine, you will need to replace ipython in all of the shell commands in this post with ipython3.

After running the commands above, the current working directory will be changed to your new profile’s directory. In this new directory, you need to make a subdirectory named static/custom. The name of the subdirectories are significant. IPython will look for and load files from within this directory because of its name. You can make the directory via the terminal by running:

Create a custom.js file inside the new directory using your favorite JavaScript editor (I prefer Sublime Text. Paste the following code into the file:

The code inside the new custom.js file registers an IPython event handler that fires when a notebook page is loaded. When it is triggered, the handler will try to load an excluder.js file located in the current directory.

The IPython notebook uses require.js to load JavaScript dependencies. In the code above, require.js is used to load the excluder.js file from the static/custom/ directory you created. The static/ doesn’t appear in the code because it is automatically pre-pended by IPython.

Create an excluder.js file in the current directory and paste the following into it:

When this code is executed, it will log the above message to the JavaScript console.

In a new terminal window, navigate to your notebook directory and start the notebook server by running:

Your default web browser will launch and show the notebook dashboard. At this point, you need to clear the cache of your web browser (you do not need to clear your history or cookies). Instructions on how to do this can be found at:

Once the cache is cleared, refresh the page. Create a new notebook or open an existing notebook and show the browser’s JavaScript console. Instructions on how to do this can be found at:

You will see “Our extension was loaded successfully” shown in the console (as seen below).


Custom Toolbar

Now that we have verified that the JavaScript is loading correctly, a custom toolbar can be created.

Toolbars must be registered by name. Every toolbar is a list of control constructing method names. Each control constructing method in the toolbar must be registered with IPython using a unique name.

Replace the code in the excluder.js file created earlier with the code below:

When executed, this code will create a cell toolbar with a checkbox. The toolbar’s unique name will be “Export Cell Exclusion”. The checkbox in the toolbar manages a new flag in the cell’s metadata called exclude_cell.

Note: The naming of the flag does not matter.

Return to the notebook dashboard and empty the cache of your web browser. Create a new notebook and in the cell toolbar drop down select “Export Cell Exclusion”. This will prepend every cell in the notebook with an “exclude_cell” checkbox (as seen below). Checking or unchecking any of these cells toggles the new flag that we added. Toggle one of the cells and save the notebook and exit.


The new exclude_cell flag can be seen in the notebook’s JSON (as seen below).

Nbconvert Plugin

The second plugin will exclude the cells during export of the notebook. This plugin will remove cells flagged with exclude_cell. This plugin will implement a custom transformer. A transformer is a component used in nbconvert to preprocess an entire notebook before the notebook is actually converted.

Note: In IPython 2.0 (not yet released) transformers have been renamed to preprocessors.

Within the same directory where your notebook resides, create a file named Insert the following code into the file:

In the code above, the IPython.nbconvert.transformer.base.Transformer base class is inherited to create a custom transformer. To get the custom transformer to load into nbconvert, an IPython nbconvert config file will be used.

Create a file named in the current directory. This is a special file name that nbconvert always looks for in the current working directory. If this file exists, nbconvert will load it as a configuration file. Insert the following configuration code into the new file:

The code above loads the transformer when exporting a notebook. Any notebooks in the same directory as the transformer and the config created above will be converted and flagged cells will be excluded (as seen below).


I hope this post has helped you understand how to write plugins for both the IPython Notebook and for nbconvert.

See below for IPython resources from Safari Books Online.

Not a subscriber? Sign up for a free trial.

Safari Books Online has the content you need

Mining the Social Web, 2nd Edition combines popular and useful social web data with analysis techniques and visualization to help you find the needles in the social haystack that you’ve been looking for—as well as many you probably didn’t even know existed. You’ll also find an appendix that covers IPython Notebook tips and tricks.
Learning IPython for Interactive Computing and Data Visualization covers all aspects of IPython, from the highly powerful interactive Python console to the numerical and visualization features that are commonly associated with IPython.
Practical Data Analysis is a hands-on guide to understanding the nature of your data and turn it into insight. It will introduce you to the use of machine learning techniques, social networks analytics, and econometrics to help your clients get insights about the pool of data they have at hand. Performing data preparation and processing over several kinds of data such as text, images, graphs, documents, and time series will also be covered, and covers the IPython Notebook.

Tags: IPython Notebook, Lubuntu, Nbconvert, notebooks, Python, Python 3.x, Require.js,

2 Responses to “Writing IPython Notebook Plugins”

  1. Matthias Bussonnier

    I would replace on('notebook_loaded.Notebook' by on on('app_loaded.App' (IIRC) or equivalent, otherwise the extension will be reloaded each time you ‘revert to checkpoint’ , which for this extension will be slightly annoying, leading to duplicate UI elements. Thanks John for doing those blog post !