Getting Started


As of version 3.0, HoloPy supports only Python 3. We recommend using the anaconda distribution of Python, which makes it easy to install the required dependencies. In the future (hopefully by the time you read this documentation), HoloPy will be available on conda-forge, so that you can install it with:

conda install -c conda-forge holopy

in a shell, terminal, or command prompt. Once you have HoloPy installed, open an IPython console or Jupyter Notebook and run:

import holopy

If this line works, skip to Using HoloPy before diving into the tutorials.

Windows Support

To find a HoloPy conda package for Windows, use

anaconda search holopy

You may need to manually install any missing dependencies (eg. emcee) from conda-forge like

conda install -c conda-forge emcee

You can also build HoloPy from source by following the instructions for Installing HoloPy for Developers.


HoloPy’s hard dependencies can be found in requirements.txt. Optional dependencies for certain calculations include:

  • a-dda (Discrete Dipole calculations of arbitrary scatterers)
  • mayavi2 (if you want to do 3D plotting [experimental])

Using HoloPy

You will probably be most comfortable using HoloPy in Jupyter (resembles Mathematica) or Spyder (resembles Matlab) interfaces. One perennially tricky issue concerns matplotlib backends. HoloPy is designed to be used with an interactive backend. In the console, try running:

from holopy import test_disp

You should see a window pop up with an image, and you should be able to change the square to a circle or diamond by using the left/right arrow keys. If you can, then you’re all set! Check out our Loading Data tutorial to start using HoloPy. If you don’t see an image, or if the arrow keys don’t do anything, you can try setting your backend with one of the following:

%matplotlib tk
%matplotlib qt
%matplotlib gtk
%matplotlib gtk3

Note that these commands will only work in an IPython console or Jupyter Notebook. If the one that you tried gave an ImportError, you should restart your kernel and try another. Note that there can only be one matplotlib backend per ipython kernel, so you have the best chance of success if you restart your kernel and immediately enter the %matplotlib command before doing anything else. Sometimes a backend will be chosen for you (that cannot be changed later) as soon as you plot something, for example by running test_disp() or show(). Trying to set to one of the above backends that is not installed on your system will result in an error, but will also prevent you from setting a different backend until you restart your kernel.

An additional option in Spyder is to change the backend through the menu: Tools > Preferences > IPython console > Graphics. It will not take effect until you restart your kernel, but it will then remember your backend for future sessions, which can be convenient.

An additional option in jupyter is to use %matplotlib nbagg to use inline interactive plots.