MacOS X installation

We outline the steps for installing MRtrix3 on MacOS X. Please consult mac_trouble_shooting 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.2 (do not install the beta version)
  • Qt version >= 5.1 [GUI components only] - important: versions prior to this will not work

Warning

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.10 (Yosemite) 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
      • Install pkg-config: port install pkgconfig
      • 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 eigen.tuxfamily.org
        Note that MRtrix3 does not yet fully support the Eigen 3.3 beta, and installation of this version may result in runtime issues. If performing a manual installation, download the latest stable release of Eigen3.
      • Install Qt5: download and install the latest version from http://download.qt.io/official_releases/qt/
        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 https://github.com/MRtrix3/mrtrix3.git

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

    git clone git@github.com:MRtrix3/mrtrix3.git

  2. Configure the MRtrix3 install:

    cd mrtrix3
./configure

    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:

    ./build

Set up MRtrix3

  1. Set your PATH in the shell startup file:

    echo "export PATH=$(pwd)/release/bin:$(pwd)/scripts:$PATH" >> ~/.bash_profile

  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 configuration file options and set anything you think might be required on your system.

Note

The above assumes that your shell will read the ~/.profile file at startup time. This is not always guaranteed, depending on how your system is configured. If you find that the above doesn’ work (e.g. typing mrview returns a ‘command not found’ error), try writing the updated PATH to a different file, for example ~/.bash_profile or ~/.bashrc. In other words, amend the command in step 1 to end with ... >> ~/.bash_profile, and see whether this allows mrview to run from a fresh terminal.

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
./build

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

    ./configure

    and re-run step 1 again.