Linux installation¶
We outline the steps for installing MRtrix3 on a Linux machine. 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 (GCC version >= 4.9, clang)
- Python version >= 2.7
- The zlib compression library
- Eigen version >= 3.2
- 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 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 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
on Fedora 24, this is reported to work:
sudo yum install git gcc-c++ python numpy eigen3-devel zlib-devel qt-devel mesa-libGL-devel
Arch Linux:
sudo pacman -Syu git python 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.9 or above, or clang)
- Python version >2.7
- NumPy
- 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).
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 ./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¶
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 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
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
~/.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. typingmrview
returns a ‘command not found’ error), try changing step 1 to instruct theset_path
script to updatePATH
within a different file, for example~/.bash_profile
or~/.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:
./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.
Setting the CPU architecture for optimal performance¶
By default, configure
will cause the build script to produce generic code
suitable for any current CPU. If you want to ensure optimal performance on your
system, you can request that configure
produce code tailored to your
specific CPU architecture, which will allow it to use all available CPU
instructions and tune the code differently. This can improve performance
particularly for linear algebra operations as Eigen will then make use of these extensions.
However, note that this means the executables produced 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 avoid changing the default.
Specifying a different CPU architecture is done by setting the ARCH
environment
variable prior to invoking ./configure
. The value of this variable will
then be passed to the compiler via the -march
option. To get the best
performance on the current system, you can specify native
as
the architecture, leaving it up to the compiler to detect your particular CPU
and its available instructions. For example:
export ARCH=native
./configure
./build
For more specific architectures, you can provide any value from the list of
specifiers understood by the compiler,
for example ARCH='sandybridge' ./configure
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 16.04, Mint 18, ..., potentially with a virtual machine if required). Then, from the main MRtrix3 folder:
./build clean
git pull
./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 bin/
, lib/
and share/
folders
onto target systems, make sure the bin/
folder location is listed in the
PATH
, and start using these commands. For example:
Create a single archive of the relevant folders (for easy deployment):
tar cvfz mrtrix3_static.tgz bin/ lib/ share/
Copy the resulting
mrtrix3_static.tgz
file over to the target system, into a suitable location.Extract the archive in this location:
tar xvfz mrtrix3_static.tgz
You can safely remove the
mrtrix3_static.tgz
file at this point.Add the
bin/
folder to the systemPATH
, e.g.:export PATH="$(pwd)/bin:$PATH"
Note that the above command will only add MRtrix3 to the
PATH
for the current session. You would need to add the equivalent line to your users’ startup scripts, using whichever mechanism is appropriate for your system.
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 (see Display issues
for details). 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 runningmrview
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
./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)/bin:$PATH"
Note that the above command will only add MRtrix3 to the PATH
for the
current session. You would need to add the equivalent line to your users’
startup scripts, using whichever mechanism is appropriate for your system.