Making a Custom IPython Notebook Kernel

IPython notebooks come with the ability to handle multiple installations of python within the same machine through their “kernel” mechanism. This is useful, for example, when you want to run both python 2 and python 3 on the same machine for development purposes.

Another use I’ve found is if some third party framework comes with it’s own a custom python interpreter that has some funky environment setup scripts to run prior to launch. In my case, I wanted to use the python distributed with the Computational Crystallography Toolbox (cctbx) as if it were it’s own ipython kernel, but the interpreter needs to set a bunch of environment variables before launching the interpreter.

Firstly, the ipykernel package needs to be installed and accessible to the version of python we’re going to make a kernel for. In the case of cctbx the python executable it’s distributed with is started using a shell script called libtbx.python.

./build/bin/libtbx.python -m pip install ipykernel

The next thing to do is to create the custom kernel. The magic command is as follows:

./build/bin/libtbx.python -m ipykernel install --prefix . --name cctbx --display-name "Python (cctbx)"

Here we create a new kernel by running ipykernel in the current directory (the prefix option). We give it then name cctbx and the display name is what it will be called in the ipython notebook.

Our newly create kernel will live in ./share/jupyter/kernels/. This is where we can configure the kernel for our heart’s desire. For cctbx all that was needed was to crack open the kernel.json and edit the command to run when launching the kernel. Afterwards the kernel.json looks something like the following:

{
   "display_name": "Python (cctbx)",  
   "language": "python",  
   "argv": [
      "/path/to/build/bin/libtbx.python",   
      "-m",   
      "ipykernel_launcher",   
      "-f",   
      "{connection_file}"  
   ] 
}

Finally, once were happy with the changes we need to install the kernel to somewhere where Jupyter can find the kernel. The user flag is optional and tells jupyter to only install it for the current user.

jupyter kernelspec install --user share/jupyter/kernels/cctbx

We can check that it was successful installed by running:

jupyter kernelspec list