MacOS X installation

We outline the steps for installing MRtrix3 on MacOS X. Please consult Troubleshooting if you encounter any issues with the configure, build or runtime operations of MRtrix3.

Check requirements

To install MRtrix3 , you will need the following:

  • a C++11 compliant compiler (e.g. clang in Xcode)
  • Python version >= 2.6 (already included in MacOS X)
  • The zlib compression library (already included in MacOS X)
  • Eigen version 3
  • Qt version >= 5.1 [GUI components only] - important: versions prior to this will not work


To run the GUI components of MRtrix3 (mrview & shview), you will also need:

  • an OpenGL 3.3 compliant graphics card and corresponding software driver - thankfully OpenGL 3.3 is supported across the entire MacOS X range with OS versions >= 10.9.

Install Dependencies

  1. Update MacOS X to version 10.9 (Mavericks) or higher - OpenGL 3.3 will typically not work on older versions

  2. Install XCode from the Apple Store

  3. Install Eigen3 and Qt5.

    There are several alternatives to do this, depending on your current system setup. The most convenient is probably to use your favorite package manager (Homebrew or MacPorts), or install one of these if you haven’t already.

    If you find your first attempt doesn’t work, please resist the temptation to try one of the other options: in our experience, this only leads to further conflicts, which won’t help installing MRtrix3 and will make things more difficult to fix later. Once you pick one of these options, we strongly recommend you stick with it, and consult the community forum if needed for advice and troubleshooting.

    • With Homebrew:
      • Install Eigen3: brew install eigen
      • Install Qt5: brew install qt5
      • Add Qt’s binaries to your path: export PATH=`brew --prefix`/opt/qt5/bin:$PATH
    • With MacPorts:
      • Install Eigen3: port install eigen3
      • Install Qt5: port install qt5
      • Add Qt’s binaries to your path: export PATH=/opt/local/libexec/qt5/bin:$PATH
    • As a last resort, you can manually install Eigen3 and Qt5: You can use this procedure if you have good reasons to avoid the other options, or if for some reason you cannot get either Homebrew or MacPorts to work.

      • Install Eigen3: download and extract the source code from
      • Install Qt5: download and install the latest version from
        You need to select the file labelled qt-opensource-mac-x64-clang-5.X.X.dmg. Note that you need to use at least Qt 5.1, since earlier versions don’t support OpenGL 3.3. We advise you to use the latest version (5.5.0 as of the last update). You can choose to install it system-wide or just in your home folder, whichever suits - just remember where you installed it.
      • Make sure Qt5 tools are in your PATH
        (edit as appropriate) export PATH=/path/to/Qt5/5.X.X/clang_64/bin:$PATH
      • Set the CFLAG variable for eigen
        (edit as appropriate) export EIGEN_CFLAGS="-isystem /where/you/extracted/eigen" Make sure not to include the final /Eigen folder in the path name - use the folder in which it resides instead!

Git setup

Set up your git environment as per the Git instructions page

Build MRtrix3

  1. Clone the MRtrix3 repository:

    git clone

    or if you have set up your SSH keys (for collaborators):

    git clone
  2. Configure the MRtrix install:

    cd mrtrix3

    If this does not work, examine the ‘configure.log’ file that is generated by this step, it may give clues as to what went wrong.

  3. Build the binaries:


Set up MRtrix3

  1. Set your PATH in the shell startup file:

    echo PATH=$(pwd)/release/bin:$(pwd)/scripts:\$PATH >> ~/.bashrc
  2. Close the terminal and start another one to ensure the startup file is read (or just type ‘bash’)

  3. type mrview to check that everything works

  4. You may also want to have a look through the List of configuration file options and set anything you think might be required on your system.

Keeping MRtrix3 up to date

  1. You can update your installation at any time by opening a Git Bash terminal in the MRtrix3 folder, and typing:

    git pull
  2. If this doesn’t work immediately, it may be that you need to re-run the configure script:


    and re-run step 1 again.


Below is a list of problems that you may encounter during installation or running of MRtrix3, along with suggested solutions.


This section is incomplete

Conflicts with previous versions of Qt

If previous versions of Qt were already installed on the system, they can sometimes conflict with the installation of MRtrix3. This can manifest in many ways, but the two most obvious one are:

  • ./configure reports using the older version, but ./build completes without errors. However, MRView crashes, complaining about OpenGL version not being sufficient.
  • ./configure reports the correct version of Qt, but ./build fails with various error messages (typically related to refined macros, with previous definitions elsewhere in the code).