macOS installation¶
We outline the steps for installing MRtrix3 on macOS. Please consult the MRtrix3 forum 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.7 (already included in macOS)
- The zlib compression library (already included in macOS)
- Eigen version >= 3.2
- 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 range with OS versions >= 10.9.
Note
If you currently do not plan to contribute to the MRtrix3 code, the most convenient way to install Mrtrix3 on macOS is to install it via homebrew.
If you do not have homebrew installed, you can install it via:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
You need to add the MRtrix3 tap to homebrew:
brew tap MRtrix3/mrtrix3
You can now install the latest version of MRtrix3 with:
brew install mrtrix3
This should be all you need to do. For all installation options type brew
info mrtrix3
. MRtrix3 will get upgraded when you upgrade all homebrew
packages brew update && brew upgrade
. If you want to avoid upgrading
MRtrix3 the next time you upgrade homebrew you can do so with brew pin
mrtrix3
.
Install Dependencies¶
Update macOS to version 10.10 (Yosemite) or higher - OpenGL 3.3 will typically not work on older versions
Install XCode from the Apple Store
Install Eigen3 and Qt5.
There are several alternative ways 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
- Install pkg-config:
brew install pkg-config
- Add Qt’s binaries to your path:
export PATH=`brew --prefix`/opt/qt5/bin:$PATH
- Install Eigen3:
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
- Install Eigen3:
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
- 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.7.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¶
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
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.
Build the binaries:
./build
Set up MRtrix3¶
Update the shell startup file, so that the shell can locate the MRtrix3 commands and scripts, by adding the
bin/
folder to yourPATH
environment variable.If you are not familiar or comfortable with modification of shell files, MRtrix3 provides a convenience script that will perform this setup for you (assuming that you are using
bash
or equivalent interpreter). From the top level MRtrix3 directory, run the following:./set_path
Close the terminal and start another one to ensure the startup file is read (or just type ‘bash’)
Type
mrview
to check that everything worksYou may also want to have a look through the List of MRtrix3 configuration file options and set anything you think might be required on your system.
Note
The above assumes that your shell will read the
~/.bash_profile
file at startup time. This is not always guaranteed, depending on how your system is configured. If you find that the above doesn’t work (e.g. typingmrview
returns a ‘command not found’ error), try changing step 1 to instruct theset_path
script to updatePATH
within a different file, for example~/.profile
or~/.bashrc
, e.g. as follows:./set_path ~/.profile
Keeping MRtrix3 up to date¶
You can update your installation at any time by opening a terminal, navigating to the MRtrix3 folder (e.g.
cd mrtrix3
), and typing:git pull ./build
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.