Linux installation

We outline the steps for installing MRtrix3 on a Linux machine. Please consult linux_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 (GCC version >= 4.8, clang)
  • Python version >= 2.6
  • NumPy
  • The zlib compression library
  • Eigen version 3.2 (do not install the beta version)
  • Qt version >= 4.7 [GUI components only]

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 - see Remote display issues for details.

Install Dependencies

The installation procedure will depend on your system. Package names may changes between distributions, and between different releases of the same distribution. The commands below are suggestions based on what has been reported to work in the past, but may need to be amended. 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 numpy libeigen3-dev zlib1g-dev libqt4-opengl-dev libgl1-mesa-dev
    
  • RPM-based distros (Fedora, CentOS):

    sudo yum install git g++ python numpy eigen3-devel zlib-devel libqt4-devel libgl1-mesa-dev
    
  • Arch Linux:

    sudo pacman -Syu git python numpy gcc zlib eigen qt5-svg
    

If this doesn’t work

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
  • your compiler (gcc 4.8 or above, or clang)
  • Python version >2.6
  • NumPy
  • the zlib compression library and its corresponding development header/include files
  • the Eigen template library (only consists of development header/include files); note that MRtrix3 may not run correctly with the beta release of Eigen, so we recommend download and installation of the latest stable release
  • Qt version >4.7, its corresponding development header/include files, and the executables required to compile the code. Note this will most likely 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).

Warning

The compiler included in Ubuntu 12.04 and other older distributions is no longer capable of compiling MRtrix3, as it now requires C++11 support. The solution is to use a newer compiler as provided by the Ubuntu toolchain PPA - follow the link for instructions on how to add the PPA. Once the PPA has been added, you’ll need to issue a sudo apt-get update, followed by sudo apt-get install g++-4.9. You will probably also need to tell ./configure to use this compiler (see ./configure -help for further options):

CXX=g++-4.9 LD=g++-4.9 ./configure

If this really doesn’t work

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 procedure described in Standalone installation on Linux.

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 (amend if you use tcsh or some other shell):

    echo "export 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 mrtrix_config_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 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.

Standalone installation on Linux

In some cases, users need to install MRtrix3 on systems running older distributions, over which they have little or no control, for example centrally-managed HPC clusters. In such cases, there genuinely is no way to install the dependencies required to compile and run MRtrix3. There are two ways to address this problem: static executables, and the standalone packager. With both approaches, you can compile MRtrix3 on a modern distro (within a virtual machine for example), package it up, and install it on any Linux system without worrying about dependencies.

Important: setting the CPU architecture

By default, configure will cause the build script to generate code suitable to run on your current CPU (using the -march=native option). This means the executables will likely not run on a different CPUs with different instruction sets, resulting in ‘illegal instruction’ runtime errors. If you intend to run MRtrix3 on a variety of different systems with a range of CPUs, or you have no idea what the CPU is on your target system, it is safest to specify a generic architecture when configuring MRtrix3, before invoking ./build. For example, assuming a 64-bit build is needed:

ARCH='x86-64' ./configure
./build

For a 32-bit build, substituting ARCH=’i686’ or similar should suffice.

Static build

The simplest approach to this problem is to build so-called static executables, which have no run-time dependencies. This can be accomplished by generating a static configuration before building the software, as follows.

First, obtain the code and extract or clone it on a modern distribution (Arch, Ubuntu 14.04, Mint 17, ..., potentially with a virtual machine if required). Then, from the main MRtrix3 folder:

./build clean
git pull
ARCH=x86-64 ./configure -static [-nogui]
./build

Note that this requires the availability of static versions of the required libraries. This is generally not a problem, most distributions will provide those by default, with the exception of Qt. If you require a static build of MRView, you will most likely need to build a static version of Qt beforehand. Use the -nogui option to skip installation of GUI components, which rely on Qt.

You can then copy the contents of the release/bin/ folder onto target systems, make sure their location is listed in the PATH, and start using these commands.

Standalone packager

In the rare cases where the static build procedure above doesn’t work for you, MRtrix3 now includes the package_mrtrix script, which is designed to package an existing and fully-functional installation from one system, so that it can be installed as a self-contained standalone package on another system. What this means is that you can now compile MRtrix3 on a modern distro (within a virtual machine for example), package it up, and install it on any Linux system without worrying about dependencies.

Note: this is not the recommended way to install MRtrix3, and may not work for your system. This is provided on a best-effort basis, as a convenience for users who genuinely have no alternative.

What it does

The package_mrtrix script is included in the top-level folder of the MRtrix3 package (if you don’t have it, use git pull to update). In essence, all it does is collate all the dynamic libraries necessary for runtime operation into a single folder, which you can then copy over and extract onto target systems. For a truly standalone installation, you need to add the -standalone option, which will also include any system libraries required for runtime operation from your current system, making them available on any target system.

Limitations

  • OpenGL support: this approach cannot magically make your system run mrview if it doesn’t already support OpenGL 3.3 and above. This is a hardware driver issue, and can only be addressed by upgrading the drivers for your system - something that may or may not be possible.
  • GUI support: while this approach collates all the X11 libraries that are needed to launch the program, it is likely that these will then dynamically attempt to load further libraries that reside on your system. Unfortunately, this can introduce binary compatibility issues, and cause the GUI components to abort. This might happen even if your system does have OpenGL 3.3 support. There is unfortunately no simple solution to this.
  • Installation on remote systems: bear in mind that running the GUI components over a remote X11 connection is not possible, since the GLX protocol does not support OpenGL 3 and above. You may be able to use an OpenGL-capable VNC connection, but if that is not possible, there is little point in installing the GUI components on the remote server. The recommendation would be to configure with the -nogui option to skip the GUI components. You should also be able to access your data over the network (e.g. using SAMBA or SSHFS), in which case you would be able to display the images by running mrview locally and loading the images over the shared network drives.

Instructions

First, obtain the code and extract or clone it on a modern distribution (Arch, Ubuntu 14.04, Mint 17, ..., potentially with a virtual machine if required). Then, from the main MRtrix3 folder:

./build clean
git pull
ARCH='x86-64' ./configure [-nogui]
./build
./package_mrtrix -standalone

Then copy the resulting _package/mrtrix3 folder to the desired location on the target system (maybe your own home folder). To make the MRtrix3 command available on the command-line, the bin/ folder needs to be added to your PATH (note this assumes that you’re running the BASH shell):

export PATH=$(pwd)/mrtrix3/release/bin:$(pwd)/mrtrix3/scripts:$PATH

The above will only set your PATH for the current session. To make this the default for new sessions, you should add the relevant line to your ~/.bashrc file:

echo export PATH=$(pwd)/mrtrix3/release/bin:$(pwd)/mrtrix3/scripts:\$PATH >> ~/.bashrc