Install Python and MNE-Python

To use MNE-Python, you need two things:

  1. A working Python interpreter and dependencies
  2. The MNE-Python package installed to the Python distribution

Step-by-step instructions to accomplish this are given below.

Note

Users who work at a facility with a site-wide install of MNE-Python (e.g. Martinos center) are encouraged to contact their technical staff about how to access and use MNE-Python, as the instructions might differ.

1. Install a Python interpreter and dependencies

There are multiple options available for getting a suitable Python interpreter running on your system. However, for a fast and up to date scientific Python environment that resolves all dependencies, we highly recommend following installation instructions for the Anaconda Python distribution. Go here to download, and follow the installation instructions:

Note

Intel’s Math Kernel Library speeds up many linear algebra comptutations, some by an order of magnitude. It is included by default in Anaconda, which makes it preferable to some other potentially viable Python interpreter options (e.g., using brew in OSX or sudo apt-get install on Ubuntu to get a usable Python interpreter).

If everything is set up correctly, you should be able to check the version of conda that is installed (your version number will probably be newer) and which python will be called when you run python:

$ conda --version
conda 3.19.1
$ which python
/home/agramfort/anaconda/bin/python

If your installation doesn’t look something like this, something went wrong and you should try to fix it. We recommend looking through the Anaconda documentation a bit, and Googling for Anaconda install tips (StackExchange results are often helpful).

Once Anaconda works properly, you can do this to resolve the MNE-Python dependencies:

$ conda install scipy matplotlib scikit-learn

To test that everything works properly, open up IPython:

$ ipython --matplotlib=qt

Now that you have a working Python environment you can install MNE-Python.

If you want to have an environment with a clean MATLAB-like interface, consider using Spyder, which can easily be installed with Anaconda as:

$ conda install spyder

2. Install the MNE-Python package

There are a many options for installing MNE-Python, but two of the most useful and common are:

  1. Use the stable release version of MNE-Python. It can be installed as:

    $ pip install mne --upgrade
    

    MNE-Python tends to release about once every six months, and this command can be used to update the install after each release.

  1. Use the development master version of MNE-Python. If you want to be able to update your MNE-Python version between releases (e.g., for bugfixes or new features), this will set you up for frequent updates:

    $ git clone git://github.com/mne-tools/mne-python.git
    $ cd mne-python
    $ python setup.py develop
    

    A cool feature of python setup.py develop is that any changes made to the files (e.g., by updating to latest master) will be reflected in mne as soon as you restart your Python interpreter. So to update to the latest version of the master development branch, you can do:

    $ git pull origin master
    

    and your MNE-Python will be updated to have the latest changes. If you plan to contribute to MNE-Python, you should follow a variant of this approach outlined in the contribution instructions.

3. Check your installation

To check that everything went fine, in ipython, type:

>>> import mne

If you get a new prompt with no error messages, you should be good to go!

A good place to start is on our Tutorials page or with our Examples Gallery.

Along the way, make frequent use of Python API Reference and User Manual to understand the capabilities of MNE.

4. Optional advanced setup

CUDA

We have developed specialized routines to make use of NVIDIA CUDA GPU processing to speed up some operations (e.g. FIR filtering) by up to 10x. If you want to use NVIDIA CUDA, you should install:

  1. the NVIDIA toolkit on your system
  2. PyCUDA
  3. skcuda

For example, on Ubuntu 15.10, a combination of system packages and git packages can be used to install the CUDA stack:

# install system packages for CUDA
$ sudo apt-get install nvidia-cuda-dev nvidia-modprobe
# install PyCUDA
$ git clone http://git.tiker.net/trees/pycuda.git
$ cd pycuda
$ ./configure.py --cuda-enable-gl
$ git submodule update --init
$ make -j 4
$ python setup.py install
# install skcuda
$ cd ..
$ git clone https://github.com/lebedov/scikit-cuda.git
$ cd scikit-cuda
$ python setup.py install

To initialize mne-python cuda support, after installing these dependencies and running their associated unit tests (to ensure your installation is correct) you can run:

$ MNE_USE_CUDA=true MNE_LOGGING_LEVEL=info python -c "import mne; mne.cuda.init_cuda()"
Enabling CUDA with 1.55 GB available memory

If you have everything installed correctly, you should see an INFO-level log message telling you your CUDA hardware’s available memory. To have CUDA initialized on startup, you can do:

>>> mne.utils.set_config('MNE_USE_CUDA', 'true') 

You can test if MNE CUDA support is working by running the associated test:

$ nosetests mne/tests/test_filter.py

If MNE_USE_CUDA=true and all tests pass with none skipped, then MNE-Python CUDA support works.

IPython (and notebooks)

In IPython, we strongly recommend using the Qt matplotlib backend for fast and correct rendering:

$ ipython --matplotlib=qt

On Linux, for example, QT is the only matplotlib backend for which 3D rendering will work correctly. On Mac OS X for other backends certain matplotlib functions might not work as expected.

To take full advantage of MNE-Python’s visualization capacities in combination with IPython notebooks and inline displaying, please explicitly add the following magic method invocation to your notebook or configure your notebook runtime accordingly:

In [1]: %matplotlib inline

If you use another Python setup and you encounter some difficulties please report them on the MNE mailing list or on github to get assistance.

Mayavi and PySurfer

Mayavi is currently only available for Python2.7. The easiest way to install mayavi is to do the following with Anaconda:

$ conda install mayavi

For other methods of installation, please consult the Mayavi documentation.

The PySurfer package, which is used for visualizing cortical source estimates, uses Mayavi and can be installed using:

$ pip install PySurfer

Some users may need to configure PySurfer before they can make full use of our visualization capabilities. Please refer to the PySurfer installation page for up to date information.

Troubleshooting

If you run into trouble when visualizing source estimates (or anything else using mayavi), you can try setting ETS_TOOLKIT environment variable:

>>> import os
>>> os.environ['ETS_TOOLKIT'] = 'qt4'
>>> os.environ['QT_API'] = 'pyqt'

This will tell Traits that we will use Qt with PyQt bindings.

If you get an error saying:

ValueError: API 'QDate' has already been set to version 1

you have run into a conflict with Traits. You can work around this by telling the interpreter to use QtGui and QtCore from pyface:

>>> from pyface.qt import QtGui, QtCore

This line should be added before any imports from mne-python.

For more information, see http://docs.enthought.com/mayavi/mayavi/building_applications.html.