Building MRtrix3 from source
The instructions below describe the process of compiling and installing MRtrix3 from source. Please consult the MRtrix3 forum if you encounter any issues.
These instructions are for more advanced users who wish to install very specific versions of MRtrix3, or make their own modifications. Most users will find it much easier to install one of the pre-compiled packages available for their platform from the main MRtrix3 website.
To install MRtrix3, you will need to have a number of dependencies available on your system, listed below. These can be installed in a number of ways, depending on your specific platform. We provide specific instructions for doing so for GNU/Linux, macOS and Microsoft Windows in the subsequent sections.
a C++11 compliant compiler (GCC version >= 5, clang);
The zlib compression library;
Eigen version >= 3.2 (>= 3.3 recommended);
Qt version >= 5.5 (but not Qt 6) [GUI components only];
libTIFF version >= 4.0 (for TIFF support);
FFTW version >= 3.0 (for improved performance in certain applications, currently only
libpng (for PNG support).
The instructions below list the most common ways to install these dependencies on Linux, macOS, and Windows platforms.
To run the GUI components of MRtrix3 (
shview), you will also need an OpenGL 3.3 compliant graphics card and
corresponding software driver.
Note that this implies you cannot run the GUI components over a remote X11 connection, since it can’t support OpenGL 3.3+ rendering. The most up-to-date recommendations in this context can be found in the relevant Wiki entry on the MRtrix3 community forum.
The installation procedure will depend on your system. Package names may changes between distributions, and between different releases of the same distribution. We provide commands to install the required dependencies on some of the most common Linux distributions below.
The commands below are suggestions based on what has been reported to work in the past, but may need to be tailored for your specific distribution. See below for hints on how to proceed in this case.
Ubuntu Linux (and derivatives, e.g. Linux Mint):
sudo apt-get install git g++ python libeigen3-dev zlib1g-dev libqt5opengl5-dev libqt5svg5-dev libgl1-mesa-dev libfftw3-dev libtiff5-dev libpng-dev
On Ubuntu 20.04 and newer, you’ll to replace
pythonin the line above with
python-is-python2if you’re still using version 2.7, which is now very deprecated).
RPM-based distros (Fedora, CentOS):
sudo yum install git g++ python eigen3-devel zlib-devel libqt5-devel libgl1-mesa-dev fftw-devel libtiff-devel libpng-devel
On Fedora 24, this is reported to work:
sudo yum install git gcc-c++ python eigen3-devel zlib-devel qt-devel mesa-libGL-devel fftw-devel libtiff-devel libpng-devel
sudo pacman -Syu git python gcc zlib eigen qt5-svg fftw libtiff libpng
You may find that your package installer is unable to find the packages
listed, or that the subsequent steps fail due to missing dependencies
./configure command). In this case, you will need
to search the package database and find the correct names for these
an appropriate C++ compiler (e.g. GCC 5 or above, or clang);
Python version >= 2.7 (version >= 3.0 strongly recommended);
zlibcompression library and its corresponding development header/include files;
the Eigen template library (only consists of development header/include files);
Qt version >= 5.5, its corresponding development header/include files, and the executables required to compile the code. Note that this can be broken up into several packages, depending on how your distribution has chosen to distribute this. You will need to get those that provide these Qt modules: Core, GUI, OpenGL, SVG, and the
mocexecutables (note these will probably be included in one of the other packages);
[optional] the TIFF library and utilities version >= 4.0, and its corresponding development header/include files;
[optional] the FFTW library version >= 3.0, and its corresponding development header/include files;
[optional] the PNG library and its corresponding development header/include files.
Compilers included in older distributions, e.g. Ubuntu 12.04, may not be
capable of compiling MRtrix3, as it requires C++11 support.
A solution is to install a newer compiler as provided by an optional addon
package repository, e.g. the Ubuntu toolchain PPA. Once the
relevant repository has been added to the distribution’s package manager,
you’ll need to update the local list of available packages (e.g.
sudo apt-get update), followed by explicit installation of the newer
version of the compiler (e.g.
sudo apt-get install g++-7).
In many instances where MRtrix3 dependencies are installed in some
non-standard fashion, the MRtrix3
configure script will not be able
to automatically identify the location and/or appropriate configuration
of those dependencies. In such cases, the MRtrix3
provides a range of environment variables that can be set by the user in
order to provide this information. Executing
configure -help provides
a list of such environment variables; in addition, if the script is unable
to detect or utilise a particular dependency properly, it will also provide a
suggestion of which environment variable may need to be set in a manner
tailored for your particular system in order to provide it with the
information it needs to locate that dependency.
If for whatever reasons you need to install MRtrix3 on a system with older dependencies, and you are unable to update the software (e.g. you want to run MRtrix3 on a centrally-managed HPC cluster), you can as a last resort use the procedures described in this community forum post.
Update macOS to version 10.10 (Yosemite) or higher (OpenGL 3.3 will typically not work on older versions);
Install XCode from the App 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.
brew install eigen
brew install qt5
brew install pkg-config
Add Qt’s binaries to your path:
export PATH=`brew --prefix`/opt/qt5/bin:$PATH
port install eigen3
port install qt5
port install pkgconfig
Add Qt’s binaries to your 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
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. 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):
Set the CFLAG variable for Eigen (edit as appropriate):
export EIGEN_CFLAGS="-isystem /where/you/extracted/eigen"Make sure not to include the final
/Eigenfolder in the path name: use the folder in which it resides instead!
Install TIFF, FFTW and PNG libraries.
All of these dependencies are installed below by the MSYS2 package manager.
When following the instructions below, use the ‘MinGW-w64 Win64 shell’; ‘MSYS2 shell’ and ‘MinGW-w64 Win32 shell’ must be avoided, as they will yield erroneous behaviour that is difficult to diagnose if used accidentally.
At time of writing, this MSYS2 system update will give a number of instructions, including: terminating the terminal when the update is completed, and modifying the shortcuts for executing the shell(s). Although these instructions are not as prominent as they could be, it is vital that they are followed correctly!
Run the program ‘MinGW-w64 Win64 Shell’ from the start menu.
Update the system packages, as per the instructions:
Close the terminal, start a new ‘MinGW-w64 Win64 Shell’, and repeat as necessary until no further packages are updated.
From the ‘MinGW-w64 Win64 Shell’ run:
pacman -S git python pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-eigen3 mingw-w64-x86_64-qt5 mingw-w64-x86_64-fftw mingw-w64-x86_64-libtiff mingw-w64-x86_64-libpng
pacmanmay fail to find a particular package from any of the available mirrors. If this occurs, you can download the relevant package from SourceForge: place both the package file and corresponding .sig file into the
/var/cache/pacman/pkgdirectory, and repeat the
pacmanmay refuse to install a particular package, claiming e.g.:
error: failed to commit transaction (conflicting files) mingw-w64-x86_64-eigen3: /mingw64 exists in filesystem Errors occurred, no packages were upgraded.
Firstly, if the offending existing target is something trivial that can be deleted, this is all that should be required. Otherwise, it is possible that MSYS2 may mistake a file existing on the filesystem as a pre-existing directory; a good example is that quoted above, where
pacmanclaims that directory
/mingw64exists, but it is in fact the two files
/mingw64.inithat cause the issue. Temporarily renaming these two files, then changing their names back after
pacmanhas completed the installation, should solve the problem.
If you intend to contribute to the development of MRtrix3, set up your git environment as per the Git instructions page
Clone the MRtrix3 repository:
git clone https://github.com/MRtrix3/mrtrix3.git
or if you have set up your SSH keys (for contributors):
git clone firstname.lastname@example.org: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:
Set up MRtrix3
Update the shell startup file, so that the locations of MRtrix3 commands and scripts will be added to your
If you are not familiar or comfortable with modification of shell files, MRtrix3 now provides a convenience script that will perform this setup for you (assuming that you are using
bashor equivalent interpreter). From the top level MRtrix3 directory, run the following:
Close the terminal and start another one to ensure the startup file is read (or just type ‘bash’)
mrviewto check that everything works
You 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.
The above assumes that your shell will read the
~/.bashrcfile 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. typing
mrviewreturns a ‘command not found’ error), try changing step 1 to instruct the
set_pathscript to update
PATHwithin a different file, for example
~/.profile, e.g. as follows:./set_path ~/.bash_profile
Keeping MRtrix3 up to date
You can update your installation at any time by opening a terminal in the MRtrix3 folder, and typing:
git pull ./build
If this doesn’t work immediately, it may be that you need to re-run the configure script:
and re-run step 1 again.