Advanced setup of MNE-Python¶

Using MNE-Python with IPython / Jupyter notebooks
Using the development version of MNE-Python (latest main)
Using MNE-Python with other Python distributions
Using MNE-Python with CUDA (NVIDIA GPU acceleration)
Off-screen rendering in MNE-Python on Linux with MESA
Troubleshooting 3D plots in MNE-Python
- 3D plotting trouble after version 0.20 upgrade on macOS
- 3D plotting trouble using mayavi 3D backend

Using MNE-Python with IPython / Jupyter notebooks ¶

When using MNE-Python within IPython or a Jupyter notebook, we strongly recommend using the Qt matplotlib backend for fast and correct rendering. On Linux, for example, Qt is the only matplotlib backend for which 3D rendering will work correctly. On macOS, certain matplotlib functions might not work as expected on backends other than Qt. Enabling Qt can be accomplished when starting IPython from a terminal:

$ ipython --matplotlib=qt

or in a Jupyter Notebook, you can use the “magic” command:

In [1]: %matplotlib qt

This will create separate pop-up windows for each figure, and has the advantage that the 3D plots will retain rich interactivity (so, for example, you can click-and-drag to rotate cortical surface activation maps).

If you are creating a static notebook or simply prefer Jupyter’s inline plot display, MNE-Python will work with the standard “inline” magic:

In [1]: %matplotlib inline

but some functionality will be lost. For example, mayavi scenes will still pop-up a separate window, but only one window at a time is possible, and interactivity within the scene is limited in non-blocking plot calls.

Windows

If you are using MNE-Python on Windows through IPython or Jupyter, you might also have to use the IPython magic command %gui qt after importing MNE-Python, Mayavi or PySurfer (see here). For example:

In [1]: from mayavi import mlab
In [2]: %gui qt

If you installed the nb_conda_kernels package into your base environment (as recommended), you should be able to launch mne-capable notebooks from within the Anaconda Navigator GUI without having to explicitly switch to the mne environment first; look for Python [conda env:mne] when choosing which notebook kernel to use. Otherwise, be sure to activate the mne environment before launching the notebook.

If you use another Python setup and you encounter some difficulties please report them on the MNE Forum or on the GitHub issues page to get assistance.

It is also possible to interact with the 3D plots without installing Qt by using the notebook 3d backend:

In [1]: import mne
In [2]: mne.viz.set_3d_backend("notebook")

The notebook 3d backend requires PyVista to be installed along with other packages, please follow Installing MNE-Python

Using the development version of MNE-Python (latest main)¶

If you want access to the latest features and bugfixes, you can easily switch from the stable version of MNE-Python to the current development version.

Warning

In between releases, function and class APIs can change without warning.

For a one-time update to latest main, make sure you’re in the conda environment where MNE-Python is installed (if you followed the default install instructions, this will be base), and use pip to upgrade:

$ conda activate name_of_my_mne_environment
$ pip install --upgrade --no-deps https://github.com/mne-tools/mne-python/archive/main.zip

If you plan to contribute to MNE-Python, or just prefer to use git rather than pip to make frequent updates, check out the contributing guide.

Using MNE-Python with other Python distributions ¶

While the Anaconda Python distribution provides many conveniences, other distributions of Python should also work with MNE-Python. In particular, Miniconda is a lightweight alternative to Anaconda that is fully compatible; like Anaconda, Miniconda includes the conda command line tool for installing new packages and managing environments; unlike Anaconda, Miniconda starts off with a minimal set of around 30 packages instead of Anaconda’s hundreds. See the installation instructions for Miniconda for more info.

It is also possible to use a system-level installation of Python (version 3.5 or higher) and use pip to install MNE-Python and its dependencies, using the provided requirements file:

curl --remote-name https://raw.githubusercontent.com/mne-tools/mne-python/main/requirements.txt
pip install --user requirements.txt

Other configurations will probably also work, but we may be unable to offer support if you encounter difficulties related to your particular Python installation choices.

Using MNE-Python with CUDA (NVIDIA GPU acceleration)¶

Some operations in MNE-Python can utilize NVIDIA CUDA GPU processing to speed up some operations (e.g. FIR filtering) by roughly an order of magnitude. To use CUDA, first ensure that you are running the NVIDIA proprietary drivers on your operating system, and then do:

$ conda install cupy
$ MNE_USE_CUDA=true python -c "import mne; mne.cuda.init_cuda(verbose=True)"
Enabling CUDA with 1.55 GB available memory

If you receive a message reporting the GPU’s available memory, CuPy is working properly. To permanently enable CUDA in MNE, you can do:

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

You can then test MNE CUDA support by running the associated test:

$ pytest mne/tests/test_filter.py -k cuda

If the tests pass, then CUDA should work in MNE. You can use CUDA in methods that state that they allow passing n_jobs='cuda', such as mne.io.Raw.filter() and mne.io.Raw.resample(), and they should run faster than the CPU-based multithreading such as n_jobs=8.

Off-screen rendering in MNE-Python on Linux with MESA ¶

On remote systems, it might be possible to use MESA software rendering (such as llvmpipe or swr) for 3D visualization (with some tweaks). For example, on CentOS 7.5 you might be able to use an environment variable to force MESA to use modern OpenGL by using this before executing spyder or python:

$ export MESA_GL_VERSION_OVERRIDE=3.3

Also, it’s possible that different software rending backends might perform better than others, such as using the llvmpipe backend rather than swr.

MESA also can have trouble with full-screen antialiasing, which you can disable with:

$ export MNE_3D_OPTION_ANTIALIAS=false

or by doing mne.viz.set_3d_options(antialias=False) within a given Python session.

Troubleshooting 3D plots in MNE-Python ¶

3D plotting trouble after version 0.20 upgrade on macOS ¶

When upgrading MNE-Python to version 0.20, some macOS users may end up with conflicting versions of some of the 3D plotting dependencies. If you plot using the pyvista 3D backend and find that you can click-drag to rotate the brain, but cannot adjust any of the settings sliders, it is likely that your versions of VTK and/or QT are incompatible. This series of commands should fix it:

$ conda uninstall vtk
$ pip uninstall -y pyvista
$ conda install vtk
$ pip install --no-cache pyvista

If you installed VTK using pip rather than conda, substitute the first line for pip uninstall -y vtk.

3D plotting trouble using mayavi 3D backend ¶

If you run into trouble when visualizing source estimates (or anything else) using mayavi, you can try setting a couple of environment variables at the beginning of your script, session, or notebook:

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

This will tell mayavi to use Qt backend with PyQt bindings, instead of the default PySide. For more information, see http://docs.enthought.com/mayavi/mayavi/building_applications.html#integrating-in-a-qt-application.