Running MRtrix3 using containers

From MRtrix version 3.0.3 onwards, official Docker and Singularity containers are provided for utilising MRtrix3 commands, enabling use of all MRtrix3 commands (including those that possess dependencies on other neuroimaging software packages) without necessitating any software installation on the user system.

Using Docker

Run terminal command

Non-GUI commands are typically executed as follows:

docker run --rm -it mrtrix3 <command>

(replacing “<command>” with the name of the command to be executed, along with any arguments / options to be provided to it)

If an MRtrix3 image has not been built on the local system, the most recent MRtrix3 Docker image will be automatically downloaded from [DockerHub](https://hub.docker.com/r/mrtrix3/mrtrix3).

Run GUI command

The following instructions have been shown to work on Linux:

xhost +local:root
docker run --rm -it -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY mrtrix3 mrview
xhost -local:root  # Run this when finished.

Explicitly build image locally

As an alternative to downloading the image from DockerHub as described above, the following instruction can be run from a location in which the MRtrix3 source code has been cloned:

docker build --tag mrtrix3 .

Set DOCKER_BUILDKIT=1 to build parts of the Docker image in parallel, which can speed up build time. Use –build-arg MAKE_JOBS=4 to build MRtrix3 with 4 processors (can substitute this with any number of processors > 0); if omitted, MRtrix3 will be built using a single thread only.

Using Singularity

Build container natively

The following instruction can be run from the location in which the MRtrix3 source code has been cloned:

singularity build MRtrix3.sif Singularity

Build container from DockerHub

This command converts the Docker image as stored on DockerHub into a Singularity container stored on the user’s local system:

singularity build MRtrix3.sif docker://mrtrix/mrtrix3:<version>

(Replace “<version>” with the specific version tag of MRtrix3 desired)

Run terminal command

Unlike Docker containers, where an explicit “docker run” command must be utilised to execute a command within a container, a Singularity image itself acts as an executable file that can be invoked directly:

MRtrix3.sif <command>

(replacing “<command>” with the name of the command to be executed, along with any arguments / options to be provided to it)

Run GUI command

The following usage has been shown to work on Linux:

singularity exec -B /run MRtrix3.sif mrview