# 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