Windows installation

We outline the steps for installing MRtrix3 for Windows using MSYS2. Please consult the MRtrix3 forum if you encounter any issues with the configure, build or runtime operations of MRtrix3.


Some of the Python scripts provided with MRtrix3 are dependent on external software tools (for instance FSL). If these packages are not available on Windows, then the corresponding MRtrix3 scripts also cannot be run on Windows. A virtual machine may therefore be required in order to use these particular scripts; though MRtrix3 may still be installed natively on Windows for other tasks.

Check requirements

To install MRtrix3, you will need the following:

  • a C++11 compliant compiler
  • Python version >= 2.7
  • The zlib compression library
  • Eigen version 3.2 (do not install the beta version)
  • Qt version >= 4.7 [GUI components only]


All of these dependencies are installed below by the MSYS2 package manager.


To run the GUI components of MRtrix3 (mrview & shview), you will also need:

  • an OpenGL 3.3 compliant graphics card and corresponding software driver


When following the instructions below, use the ‘MinGW-w64 Win64 shell’; ‘MSYS2 shell’ and ‘MinGW-w64 Win32 shell’ should be avoided.

Install and update MSYS2

  1. Download and install the most recent 64-bit MSYS2 installer from (msys2-x86_64-*.exe).

  2. Run the program ‘MinGW-w64 Win64 Shell’ from the start menu.

  3. Update the system packages:



    Future versions of MSYS2 will drop update-core. If your version came without update-core, it is probably safe to skip this step.


At time of writing, this MSYS2 system update will give a number of instructions, including: terminating the terminal when the update is completed, and modifying the shortcuts for executing the shell(s). Although these instructions are not as prominent as they could be, it is vital that they are followed correctly!

  1. Close the shell and start ‘MinGW-w64 Win64 Shell’

  2. Update the other packages:

    pacman -Su

Install MRtrix3 dependencies

  1. From the ‘MinGW-w64 Win64 Shell’ run:

        pacman -S git python pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-eigen3 mingw-w64-x86_64-qt5
    Sometimes ``pacman`` may fail to find a particular package from any of
    the available mirrors. If this occurs, you can download the relevant
    package from `SourceForge <>`__:
    place both the package file and corresponding .sig file into the
    ``/var/cache/pacman/pkg`` directory, and repeat the ``pacman`` call above.
    Sometimes ``pacman`` may refuse to install a particular package, claiming e.g.::
        error: failed to commit transaction (conflicting files)
        mingw-w64-x86_64-eigen3: /mingw64 exists in filesystem
        Errors occurred, no packages were upgraded.
    Firstly, if the offending existing target is something trivial that can
    be deleted, this is all that should be required. Otherwise, it is possible
    that MSYS2 may mistake a _file_ existing on the filesystem as a
    pre-existing _directory_; a good example is that quoted above, where
    ``pacman`` claims that directory ``/mingw64`` exists, but it is in fact the
    two files ``/mingw64.exe`` and ``/mingw64.ini`` that cause the issue.
    Temporarily renaming these two files, then changing their names back after
    ``pacman`` has completed the installation, should solve the problem.

Set up git and download MRtrix3 sources

  1. Configure global settings for Git in the ‘MinGW-w64 Win64 Shell’:

    git config --global "John Doe"
    git config --global
    git config --global push.default upstream
  2. Clone the MRtrix3 repository:

    git clone

Build MRtrix3

  1. Configure the MRtrix3 install:

    cd mrtrix3

    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.

  2. Build the binaries:


Set up MRtrix3

  1. 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:

  2. Close the terminal and start another one to ensure the startup file is read (or just type ‘bash’)

  3. Type mrview to check that everything works

  4. You 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.


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. typing mrview returns a ‘command not found’ error), try changing step 1 to instruct the set_path script to update PATH within a different file, for example ~/.bash_profile or ~/.profile, e.g. as follows:

./set_path ~/.bash_profile

Keeping MRtrix3 up to date

  1. You can update your installation at any time by typing:

    git pull
  2. If this doesn’t work immediately, it may be that you need to re-run the configure script:


    and re-run step 1 again.

Compiling external projects with msys2

In msys2, the ln -s command actually creates a copy of the target, not a symbolic link. By doing so, the build script is unable to identify the location of the MRtrix libraries when trying to compile an external module.

The simplest way around this is simply to invoke the build script of the main MRtrix3 install directly. For example, if compiling an external project called myproject, residing in a folder alongside the main mrtrix3 folder, the build script can be invoked with:

# current working directory is 'myproject':

If you really want a symbolic link, one solution is to use a standard Windows command prompt, with Administrator privileges: In the file explorer, go to C:\Windows\system32, locate the file cmd.exe, right-click and select ‘Run as administrator’. Within this prompt, use the mklink command (note that the argument order passed to mklink is reversed with respect to ln -s; i.e. provide the location of the link, then the target). Make sure that you provide the full path to both link and target, e.g.:

mklink C:\msys64\home\username\src\my_project\build C:\msys64\home\username\src\MRtrix3\build

, and msys64 should be able to interpret the softlink path correctly (confirm with ls -la).

I have also found recently that the build script will not correctly detect use of a softlink for compiling an external project when run under Python2, so Python3 must be used explicitly.