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.

Warning

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.


Install Dependencies

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.

Required dependencies:

  • a C++11 compliant compiler (GCC version >= 5, clang);

  • Python version >= 2.7 (>= 3 strongly recommended due to deprecation of Python2);

  • The zlib compression library;

  • Eigen version >= 3.2 (>= 3.3 recommended);

  • Qt version >= 5.5 (but not Qt 6) [GUI components only];

and optionally:

  • libTIFF version >= 4.0 (for TIFF support);

  • FFTW version >= 3.0 (for improved performance in certain applications, currently only mrdegibbs);

  • libpng (for PNG support).

The instructions below list the most common ways to install these dependencies on Linux, macOS, and Windows platforms.

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.

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.

Linux

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.

Warning

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
    

    Note

    On Ubuntu 20.04 and newer, you’ll to replace python in the line above with python-is-python3 (or python-is-python2 if 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
    
  • Arch Linux:

    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 (particularly the ./configure command). In this case, you will need to search the package database and find the correct names for these packages:

  • git;

  • an appropriate C++ compiler (e.g. GCC 5 or above, or clang);

  • Python version >= 2.7 (version >= 3.0 strongly recommended);

  • the zlib compression 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 qmake, rcc & moc executables (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.

Warning

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).

Note

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 configure script 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.

See also

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.

macOS

  1. Update macOS to version 10.10 (Yosemite) or higher (OpenGL 3.3 will typically not work on older versions);

  2. Install XCode from the App Store;

  3. 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

    • 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

      • 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): 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!

  4. Install TIFF, FFTW and PNG libraries.

    • With Homebrew:

      • Install TIFF: brew install libtiff

      • Install FFTW: brew install fftw

      • Install PNG: brew install libpng

    • With MacPorts:

      • Install TIFF: port install tiff

      • Install FFTW: port install fftw-3

      • Install PNG: port install libpng

Windows

All of these dependencies are installed below by the MSYS2 package manager.

Warning

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.

Warning

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!

  1. Download and install the most recent 64-bit MSYS2 installer from http://msys2.github.io/ (msys2-x86_64-*.exe), and following the installation instructions from the MSYS2 wiki.

  2. Run the program ‘MinGW-w64 Win64 Shell’ from the start menu.

  3. Update the system packages, as per the instructions:

    pacman -Syuu
    

    Close the terminal, start a new ‘MinGW-w64 Win64 Shell’, and repeat as necessary until no further packages are updated.

  4. 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
    

    Sometimes pacman may 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/pkg directory, and repeat the pacman call above.

    Sometimes pacman may 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 pacman claims that directory /mingw64 exists, but it is in fact the two files /mingw64.exe and /mingw64.ini that cause the issue. Temporarily renaming these two files, then changing their names back after pacman has completed the installation, should solve the problem.


Git setup

If you intend to contribute to the development of MRtrix3, 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 contributors):

    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. Update the shell startup file, so that the locations of MRtrix3 commands and scripts will be added to your PATH envionment variable.

    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 bash or equivalent interpreter). From the top level MRtrix3 directory, run the following:

    ./set_path
    
  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 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 ~/.bashrc 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. typing mrview returns a ‘command not found’ error), try changing step 1 to instruct the set_path script to update PATH within a different file, for example ~/.bash_profile or ~/.profile, e.g. as follows:

./set_path ~/.bash_profile

Keeping MRtrix3 up to date

  1. You can update your installation at any time by opening a 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.