MRtrix is now available as a package on Debian and Ubuntu systems using the NeuroDebian repository. This provides a simple and effective way of installing MRtrix, along with numerous other related packages. For more information, refer to the instructions on the NeuroDebian repository. Note that there is no guarantee that the version available on this repository is the most up to date.

The rest of this page provides instructions for installing MRtrix from source. MRtrix depends on a number of other packages. Most, if not all of these packages should be available on any recent Linux distribution via the appropriate package manager. MRtrix has been written and tested on Ubuntu Linux versions 7.10 (Gutsy) through to 10.10 (Maverick). On all these distributions, all dependencies are available via the Synaptic Package Manager.

## Quick install

On Ubuntu systems (and most likely Debian too), the following instructions should work with no modifications:

### First-time installations: installing dependencies

The first time you install MRtrix, you will need to also install a number of required packages. The following step installs these dependencies on Ubuntu systems - for other distributions, you'll need to use the equivalent commands as appropriate (see below). You will only need to perform this step the first time you install MRtrix:

    $ sudo apt-get install g++ python libglib2.0-dev libgtk2.0-dev libglibmm-2.4-dev libgtkmm-2.4-dev libgtkglext1-dev libgsl0-dev libgl1-mesa-dev libglu1-mesa-dev

### Installing MRtrix

Once the dependencies have been installed, the following steps will need to be performed for every install or update of MRtrix:

    $ tar xfj mrtrix-0.2.X.tar.bz2
    $ cd mrtrix-0.2.X
    $ ./build
    $ sudo ./build install

On other distributions, different steps may be required to install the required dependencies, and/or to install the compiled executables. These steps are outlined in detail below.

## Required dependencies

Before any of the programs included in the MRtrix packages can be used, they need to be compiled (i.e. translated into machine code suitable for your specific computer platform). This will generate the required executables and dynamic library. Certain packages and dependencies are needed for this step. A subset of these packages will also be required to run the executables. These packages are:

### Needed for the compilation step (build):

g++ - the GNU C++ compiler (version > 4.0.0 recommended)
  available from http://gcc.gnu.org/
python (version > 2.5 recommended)
  available from http://www.python.org/
development packages for the run-time dependencies
  as listed below

On Ubuntu, these packages can be installed using the Synaptic Package Manager, and can be found under the names 'g++' and 'python'.

### Also needed at run-time:

The developement version of these packages is required for the compilation step, while the run-time versions are needed at run-time:

glib (version > 2.16)
gtk+ (version > 2.12)
  both available from http://www.gtk.org/
glibmm (version > 2.16)
gtkmm (version > 2.12)
  both available from http://www.gtkmm.org/
gtkglext (version > 1.0)
  available from http://www.k-3d.org/gtkglext/Main_Page
GSL (GNU Scientific Library; version > 1.8)
  available from http://www.gnu.org/software/gsl/
a working OpenGL implementation (version > 1.2)
  for best results on Linux, we recommend the use of an nVidia® graphics card together with the nVidia® proprietory drivers. These drivers may be available via the distribution package manager (this is the case with Ubuntu Linux). If not, they can be downloaded from http://www.nvidia.com/

On Ubuntu, these packages can be installed using the Synaptic Package Manager, and can be found under the names 'libglib2.0-dev', 'libgtk2.0-dev', 'libglibmm-2.4-dev', 'libgtkmm-2.4-dev', 'libgtkglext1-dev', 'libgsl0-dev', 'libgl1-mesa-dev' (for a generic OpenGL implementation - the nVidia® driver already includes the required development files), and 'libglu1-mesa-dev'.

top

## The compilation step

Once all dependencies are installed, MRtrix can be compiled by issuing the commands (modify as appropriate):

    $ tar xjf mrtrix-0.2.X.tar.bz2
    $ cd mrtrix-0.2.X/
    $ ./build

If this completes with no errors, all executables should be located in the `bin/` folder, and the `libmrtrix-0_2_X.so` dynamic library should be located in the `lib/` folder.

If any errors do occur, you may need to modify the configuration file. The relevant file will be located in the `sysconf/` folder, will have a `*.py` suffix, and will be named according to the target platform. Unfortunately a full discussion of the various options that can be modified is beyond the scope of this document.

top

## Installation of executables

Once all executables and the dynamic library have been successfully created, they can be made available for use. The recommended installation procedure is as follows (note that this can be tailored to your needs). The following commands will typically need to be issued from the root account. If you do not have root or administrative access to your system, you can simply install the files to a location that you have write permissions for (i.e. anywhere in your home folder), in which case the following commands can be issued from your own account.

Note: on Ubuntu and other systems without a root account, simply type `sudo` as the first word on the command line (see this page for details).

The simplest way to perform this step is to use the special `install` target (as root if the destination is not user-writable):

    # ./build install

By default, this will copy the executables and dynamic library to the folder `/opt/mrtrix`. To ensure these are in the system path, it will also create symbolic links to them in the folders `/usr/bin` (for the executables) and `/usr/lib` (for the dynamic library). Finally , it will also create a default system-wide configuration file in `/etc/mrtrix.conf`, to enable multi-threading on all cores as detected by the build script.

If the files need to be installed to a different folder, a different prefix can be specified as an additional parameter:

    # ./build install=/usr/local

When installing to a location that is not in the path (such as the `/opt` folder), the simplest way to make the executables available is to create symbolic links to the executables in a standard location such as `/usr/bin` or `/usr/local/bin`. By default, the install step will create symbolic links in the `/usr/bin` and `/usr/lib` for the executables and dynamic library respectively. This can be disabled by specifying an empty path to the linkto special target:

    # ./build install linkto=

A different location can also be specified by passing a suitable prefix as an additional parameter. For example:

    # ./build install=/usr/local/mrtrix linkto=/usr/local

will copy the executables and dynamic library in `/usr/local/mrtrix/bin` and `/usr/local/mrtrix/lib` respectively, and then create symbolic links to these in the corresponding `/usr/local/bin` and `/usr/local/lib` folders.

### If the executables are not in the path:

In some cases, it may not be possible to install the executables (or symbolic links to them) into a location that is in the default path. This can happen for instance if installing into a user account. In these cases, the location of the executables needs to be added to the PATH environment variable, and the location of the dynamic library needs to be added to the LD_LIBRARY_PATH environment variable (alternatively, it may also be possible to add the latter to the dynamic loader's search path, although this is system-specific).

This can typically be done by adding a couple of lines to the relevant startup script. Unfortunately, each Unix variant may use a different procedure for this. For single user accounts, it should be sufficient to add these lines to the `~/.bashrc` file:

    PATH=/home/user/mrtrix/bin:$PATH
    LD_LIBRARY_PATH=/home/user/mrtrix/lib

For C shell users (csh or tcsh), the following lines should be added to the `~/.cshrc`:

    setenv PATH /opt/mrtrix/bin:$PATH
    setenv LD_LIBRARY_PATH /opt/mrtrix/lib/

top

## Final configuration

Once the software is up and running, is it worth taking the time to perform a few simple configurations steps. The following important application behaviours can be modified by setting the relevant variables in the configuration file (described in more detail in the Appendix). Note that if the configuration file does not exist, or if the variables are not set, default values will be used instead.

Enable multi-threading
  If MRtrix is installed on a multi-processor or multi-core system, some of the more CPU intensive tasks can take advantage of this by performing the processing in parallel across some or all of the CPU cores. Currently, the CSD computation and tractography programs are both ready for multi-threading, and will therefore take substantially less time if multi-threading is enabled. This is done by adding the following line to your configuration file:

      NumberOfThreads: 4

  with the number set appropriately for your system. Note that a default configuration file with this parameter already set to the appropriate value should already exist if the software was installed using the `./build install` command (see above).
Left-right convention for Analyse images
  There is some ambiguity in the Analyse format as to whether images are stored in left to right order or in the reverse order. This can lead to a great deal of confusion, and for this reason, it is not recommended to use the Analyse format if it can be avoided. For those cases when you need to use this format, the left-right ordering convention can be set by adding this line to your configuration file:

      Analyse.LeftToRight: false

  By default, Analyse images are assumed to be stored left to right.