A tool to install a kernelspec referring to an existing virtualenv — perfect for running a matplotlib notebook in OSX.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Suppose you want run a Jupyter notebook, or console, with an IPython kernel and some additional libraries. Even if in principle you should be able to install such a software stack (at least partially) in a virtualenv, under certain circumstances this can become quite cumbersome.

In particular this is the case if you use Python 2.7 on OS X and want to add matplotlib to your stack: the GUI backend of matplotlib requires you to use a Frameworks version of Python, that is not what virtualenv provides!

A basic woraround is to run the system (or brewed) Python executable (not the virtualenv one), but setting the $PYTHONHOME environment variable to point to your virtualenv home, that is setting such variable equal to the value of $VIRTUAL_ENV environment variable.

The jupyter-virtualenv-osx script automates the creation of an IPython kernel configuration implementing the above workaround.

How to use this script

First of all, I suggest to use the homebrew version of Python

brew install python

that (in recent brews) is a Frameworks one, so it will work with the matlab GUI.

Then you have various choices: you can install Jupyter (and IPyhon) system-wide, or in the virtualenv; then you can add to the virtualenv matplotlib, and the other libraries you need.

Provided that you have the jupyter_client and ipykernel packages installed so that you can import them, and you have activated the virtualenv containing the libraries you want your IPython kernel to use, just run

python jupyter-virtualenv-osx.py --user --name my_env

Now if you open a notebook using my_env kernel, or launch

jupyter console --kernel=my_env

and issue the magic command %matplotlib you'll see

Using matplotlib backend: MacOSX

in your output, meaning that the native backend has been selected.

Assuming you want to put everything in a virtualenv (that is the solution I suggest), the complete set of commands you'll need are

virtualenv my_venv
source my_venv/bin/activate

or, if using virtualenvwrapper:

mkvirtualenv my_venv

now install

pip install jupyter ipykernel matplotlib

finally, run this scrpit

python jupyter-virtualenv-osx.py --user --name "My Env"

How it works

This script will create a kernel configuration like the following

  "argv": [
  "env": {
    "PYTHONHOME": os.environ['VIRTUAL_ENV']
  "language": "python2",
  "display_name": name

instructing Jupyter to use the brewed Python to run the IPython kernel, and setting the environment variable $PYTHONHOME to be equal to the virtualenv home $VIRTUAL_ENV.