We outline the steps for installing MRtrix3 on a Linux machine. Please consult Troubleshooting if you encounter any issues with the configure, build or runtime operations of MRtrix3.
To install MRtrix3, you will need the following:
- a C++11 compliant compiler (GCC version >= 4.8, clang)
- Python version >= 2.6
- The zlib compression library
- Eigen version 3
- Qt version >= 4.7 [GUI components only]
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 - see Remote display issues for details.
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 libeigen3-dev zlib1g-dev libqt4-opengl-dev libgl1-mesa-dev
RPM-based distros (Fedora, CentOS):
sudo yum install git g++ python eigen3-devel zlib-devel libqt4-devel libgl1-mesa-dev
sudo pacman -Syu git python 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
./configure command). In this case, you will need
to search the package database and find the correct names for these
- your compiler (gcc 4.8 or above, or clang)
- Python version >2.6
- the zlib compression library and its corresponding development header/include files
- the Eigen template library (only consists of development header/include files)
- 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).
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
sudo apt-get install g++-4.9. You will probably also need to tell
./configure to use this compiler (see
./configure -help for
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.
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 email@example.com:MRtrix3/mrtrix3.git
Configure the MRtrix 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¶
Set your PATH in the shell startup file (amend if you use tcsh or some other shell):
echo PATH=$(pwd)/release/bin:$(pwd)/scripts:\$PATH >> ~/.bashrc
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 configuration file options and set anything you think might be required on your system.
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.
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¶
configure will cause the build script to generate code
suitable to run on your current CPU (using the
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.
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
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.
In the rare cases where the static build procedure
above doesn’t work for you, MRtrix3 now includes the
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¶
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.
- 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
-noguioption 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.
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
./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
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
echo export PATH=$(pwd)/mrtrix3/release/bin:$(pwd)/mrtrix3/scripts:\$PATH >> ~/.bashrc
Below is a list of problems that you may encounter during installation or running of MRtrix3, along with suggested solutions.
OpenGL version 3.3 not supported¶
This will typically lead to MRView crashing with a message such as:
mrview: [ERROR] GLSL log [vertex shader]: ERROR: version '330' is not supported
There are three main reasons for this:
Attempting to run MRView using X11 forwarding. This will not work without some effort, see Remote display issues for details.
Your installation genuinely does not support OpenGL 3.3. In this case, the solution will involve figuring out:
- whether your graphics hardware can support OpenGL 3.3 at all;
- whether your Linux distribution provides any drivers for your graphics hardware that can support OpenGL 3.3;
- if not, whether the manufacturer of your graphics hardware provides drivers for Linux that can be installed on your distribution;
- how to install these drivers - a process that is invariably distribution-specific, and beyond the scope of this document. If you’re having serious issues with this, you should consider asking on the MRtrix3 community forum, you will often find others have come across similar issues and can provide useful advice. If you do, make sure you provide as much information as you can (at the very least, your exact distribution, including which version of it, the exact model of your graphics hardware, and what you’ve tried so far).
Your installation does support OpenGL 3.3, but only provides access to the 3.3 functionality through the core profile, not through the compatibility profile. This seems to be an issue particularly on more recent versions of Ubuntu 14.04. To see whether this is the problem, you only need to add the line:
to your MRtrix configuration file (typically,
~/.mrtrix.conf). If it doesn’t work, you’re probably stuck with reason 2.