Overview

Sometimes it can be difficult to get an entire working stack of vispy and its dependencies, especially with jupyter and friends involved. In this document we'll try to keep living walkthrough-style guides using particular working versions of packages. If something doesn't work, please edit it to update or create an issue here.

Pip installation (virtualenv)

We strongly encourage the use of virtual environments with plato as opposed to installing into your home directory (python setup.py install --user or pip install -e). This is because of how easy it is to mix inconsistent versions of jupyter kernels, ipywidgets, the notebook extension, and vispy if you have cruft from other installations lying around. This method will use the system site-packages directory as a base, in case you want to use versions of (for example) pyside, numpy, tensorflow, or other packages that are installed by your package manager. First set up the environment:

mkdir -p ~/env
python -m venv --system-site-packages ~/env/plato
# this line is needed each time you wish to use the packages installed here
source ~/env/plato/bin/activate

Install jupyter and its dependencies, forcing it to be installed within the environment (an externally-installed jupyter may not have the kernel set up to work inside the virtual environment, for example); note that vispy 0.5 doesn't work with ipywidgets 7 or greater (if you need to use ipywidgets 7 for some reason, installing a prerelease vispy 0.6 may work):

pip install -I jupyter ipywidgets==6.0.1
jupyter nbextension enable --py --sys-prefix widgetsnbextension

Finally, install plato and any other dependencies:

pip install matplotlib vispy plato-draw

Possible additional steps for jupyter notebooks

The instructions above should suffice for environments that began with a "clean slate." If other installations of any of the components exist, however, they can sometimes interfere with finding the correct versions that were just installed by these instructions. As a first step, make sure that the just-installed version of the python packages are found using something like this inside a notebook:

import sys
print(sys.executable)

import importlib
for name in ['ipywidgets', 'widgetsnbextension', 'vispy', 'plato']:
    m = importlib.import_module(name)
    print('{}: {}, {}'.format(name, m.__file__, m.__version__))

If a python executable that is not the one inside the virtualenv is found, you may need to remove an old kernel specification:

jupyter kernelspec remove python3
python -m ipykernel install --sys-prefix

If the ipywidgets javascript is still not found correctly, you may have an old or external version of ipywidgets; in that case, just enable the updated kernel extension:

jupyter nbextension enable --py --sys-prefix widgetsnbextension

Vispy and Qt

Vispy can use a number of python qt wrapper backends. If you're using PySide, for example, you will need to install qt version 4 instead of 5 using your OS package manager or conda.