Installing HyperSpy

The easiest way to install HyperSpy in Microsoft Windows is installing the HyperSpy Bundle.

For quick instructions on how to install HyperSpy in Linux, MacOs or Windows using the Anaconda Python distribution see Quick instructions to install HyperSpy using Anaconda (Linux, MacOs, Windows).

Those experienced with Python may like to Install using Python installers or Install from source.


Since version 0.8.4 HyperSpy only supports Python 3. If you need to install HyperSpy in Python 2.7 install HyperSpy 0.8.3.

HyperSpy Bundle for Microsoft Windows

New in version 0.6.

The easiest way to install HyperSpy in Windows is installing the HyperSpy Bundle. This is a customised WinPython distribution that includes HyperSpy, all its dependencies and many other scientific Python packages.

For details and download links go to

Quick instructions to install HyperSpy using Anaconda (Linux, MacOs, Windows)

Anaconda is recommended for the best performance (it is compiled using Intel MKL libraries) and the easiest installation. The academic license is free.

  1. Download and install Anaconda. If you are not familiar with Anaconda please refer to their User Guide for details.

  2. Then install HyperSpy executing the following conda commands in the Anaconda Prompt, Linux/Mac Terminal or Microsoft Windows Command Prompt. (This depends on your OS and how you have installed Anaconda, see the Anaconda User Guide) for details.

    $ conda install hyperspy -c conda-forge
  3. (optional) Since HyperSpy v1.3 the traitsui GUI elements are not installed automatically (but the Jupyter GUI elements are). To install them:

    $ conda install hyperspy-gui-traitsui -c conda-forge


Since version 0.8.4 HyperSpy only supports Python 3. If you need to install HyperSpy in Python 2.7 install version 0.8.3:

$ conda install traitsui
$ pip install --upgrade hyperspy==0.8.3-1

To enable context-menu (right-click) startup in a chosen folder, install start_jupyter_cm. (Currently only available for Gnome and Windows, not MacOS.)

For more options and details read the rest of the documentation.

Install using Python installers

HyperSpy is listed in the Python Package Index. Therefore, it can be automatically downloaded and installed pip. You may need to install pip for the following commands to run.

Install using pip:

$ pip install hyperspy


Since version 0.8.4 HyperSpy only supports Python 3. If you need to install HyperSpy in Python 2.7 install version 0.8.3:

$ pip install --upgrade hyperspy==0.8.3-1

pip installs automatically the strictly required libraries. However, for full functionality you may need to install some other dependencies. To install with full functionality:

$ pip install hyperspy[all]

Alternatively you can select the extra functionalities required:

  • learning to install required libraries for some machine learning features.
  • gui-jupyter to install required libraries to use the Jupyter widgets GUI elements.
  • gui-traitsui to install required libraries to use the GUI elements based on traitsui
  • test to install required libraries to run HyperSpy’s unit tests.
  • mrcz to install the mrcz plugin.
  • doc to install required libraries to build HyperSpy’s documentation.
  • speed install optional libraries that speed up some functionalities.

For example:

$ pip install hyperspy[learning, gui-jupyter]

See also Installing the required libraries.

Finally, be aware that HyperSpy depends on a number of libraries that usually need to be compiled and therefore installing HyperSpy may require development tools. If the above does not work for you remember that the easiest way to install HyperSpy is using Anaconda.

Install from a binary

We provide binary distributions for Windows (see the Downloads section of the website). To install easily in other platforms see Install using Python installers

Install from source

Released version

To install from source grab a tar.gz release and in Linux/Mac (requires to Installing the required libraries manually):

$ tar -xzf hyperspy.tar.gz
$ cd hyperspy
$ python install

You can also use a Python installer, e.g.

$ pip install hyperspy.tar.gz

Development version

To get the development version from our git repository you need to install git. Then just do:

$ git clone

To install HyperSpy you could proceed like in Released version. However, if you are installing from the development version most likely you will prefer to install HyperSpy using pip development mode:

$ cd hyperspy
$ pip install -e ./

All required dependencies are automatically installed by pip. However, for extra functionality you may need to install some extra dependencies, see Installing the required libraries. Note the pip installer requires root to install, so for Ubuntu:

$ cd hyperspy
$ sudo pip install -e ./

With development mode generates or updates git post-checkout hook, which will cleanup the cythonized c files, cythonize it again and run `build_ext --inplace` after the next checkout.

Creating Debian/Ubuntu binaries

You can create binaries for Debian/Ubuntu from the source by running the release_debian script

$ ./release_debian


For this to work, the following packages must be installed in your system python-stdeb, debhelper, dpkg-dev and python-argparser are required.

Installing the required libraries

In addition to the libraries that are automatically installed when installing HyperSpy using pip (see Install using Python installers), if HyperSpy is going to be installed from source, Cython is also required. Also, to compile the documentation sphinxcontrib-napoleon and sphinx_rtd_theme are required.

In case some of the required libraries are not automatically installed when installing from source in a conda environment, these can be obtained beforehand by installing and removing hyperspy from that environment;

Known issues


  • If HyperSpy fails to start in Windows try installing the Microsoft Visual before reporting a bug.

  • Concerning older installations with the “Hyperspy here” context menus: Due to a Python bug sometimes uninstalling HyperSpy does not uninstall the “Hyperspy here” entries in the context menu. Please run the following code in a Windows Terminal (command line prompt) with administrator rights to remove the entries manually:

    $ uninstall_hyperspy_here
  • If HyperSpy raises a MemoryError exception:

    • Install the 64bit version if you’re using the 32bit one and you are running HyperSpy in a 64bit system.
    • Increase the available RAM by closing other applications or physically adding more RAM to your computer.