+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](https://bitbucket.org/glotzer/plato/issues/new).

+If 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:

+python -m venv --system-site-packages ~/env/plato

+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 doesn't currently work with ipywidgets 7 or greater:

+pip install -I jupyter ipywidgets==6.0.0                                                                                  

+Finally, install plato and any other dependencies:

+pip install matplotlib plato-draw

+conda install -c conda-forge ipywidgets=5.2.2 notebook=4.4.1 widgetsnbextension=1.2.6

+conda install pyside matplotlib qt=4.8.7                      

+1. Using PySide as the desktop GUI backend. Because it is a wrapper around Qt, it can be difficult to get consistently-linked versions without using a package manager. Furthermore, the pyside devs can't currently support windows for python3.5 and greater [link](https://github.com/pyside/PySide/issues/132), so they do not provide python3.5-and-greater packages for any OS. We could make plato backend-agnostic ([link to proposal](https://docs.google.com/document/d/1nUzkUD0PsiXYHvZY7HtNRX0hGkbWXfxrHpEUEbMjeZY)) to work around needing pyside, so let Matthew know if you're interested in helping fix this!

+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](https://bitbucket.org/glotzer/plato/issues/new). Some more general (non version-specific) troubleshooting-type information can be found [in the documentation](https://glotzerlab.engin.umich.edu/plato/troubleshooting.html).

+

+There are a few pain points with plato's dependencies:

+

+1. Using PySide as the desktop GUI backend. Because it is a wrapper around Qt, it can be difficult to get consistently-linked versions without using a package manager. Furthermore, the pyside devs can't currently support windows for python3.5 and greater [https://github.com/pyside/PySide/issues/132](link), so they do not provide python3.5-and-greater packages for any OS. We could make plato backend-agnostic ([https://docs.google.com/document/d/1nUzkUD0PsiXYHvZY7HtNRX0hGkbWXfxrHpEUEbMjeZY](link to proposal)) to work around needing pyside, so let Matthew know if you're interested in helping fix this!

+2. Using jupyter notebooks. The python packages `notebook` (jupyter notebook server library), `ipywidgets` (python-side notebook widgets code), and `widgetsnbextension` (browser-side notebook widgets code) need to have consistent versions installed simultaneously. This difficulty is somewhat increased by jupyter's extension interface using global state inside your home directory.

+

+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 [https://bitbucket.org/glotzer/plato/issues/new](here). Some more general (non version-specific) troubleshooting-type information can be found [https://glotzerlab.engin.umich.edu/plato/troubleshooting.html](in the documentation).

+

+## Conda installation

+

+This gives consistent versions for desktop (plato.viz) usage and jupyter notebook usage.

+

+```shell

+~/.anaconda3/bin/conda create -n plato python=3.5

+source ~/.anaconda3/bin/activate plato                       

+conda install -c conda-forge ipywidgets==5.2.2 notebook==4.4.1 widgetsnbextension==1.2.6

+conda config --add channels file:///nfs/glotzer/software/conda-private                                        

+conda install pyside matplotlib                             

+cd /path/to/plato

+pip install -r requirements_https.txt

+cd

+```

+

+## Pip installation (virtualenv)

+

+This will at least work for jupyter notebooks; pyside installation depends on having installed Qt using another method. Set up the environment:

+

+```shell

+mkdir -p ~/env

+python -m venv ~/env/plato

+source ~/env/plato/bin/activate

+```

+

+Select only one of the two lines below, depending on which way you authenticate to bitbucket:

+

+```shell

+pip install ipywidgets==5.2.2 notebook==4.4.1 widgetsnbextension==1.2.6 ipykernel git+https://github.com/vispy/vispy.git git+https://bitbucket.org/glotzer/peact.git@master git+https://bitbucket.org/glotzer/plato.git@master

+pip install ipywidgets==5.2.2 notebook==4.4.1 widgetsnbextension==1.2.6 ipykernel git+https://github.com/vispy/vispy.git git+ssh://git@bitbucket.org/glotzer/peact.git@master git+ssh://git@bitbucket.org/glotzer/plato.git@master 

+```

+

+Finally, link up the pieces needed by jupyter:

+

+```shell

+~/env/plato/bin/jupyter nbextension enable --py widgetsnbextension

+python -m ipykernel install --user