Installing on Windows Subsystem for Linux (WSL)

Microsoft recently released the Windows subsystem for Linux (WSL), which enables you to install and run a Linux environment on Windows 10 with near-native performance. This allows Windows users to access a range of research applications that would otherwise only be available on Unix-like systems. This includes packages that some MRtrix3 scripts (dwifslpreproc, dwibiascorrect, 5ttgen, …) rely on, notably FSL and ANTs. It makes sense therefore to also install MRtrix3 within the WSL to allow these scripts to work.

It is certainly possible to build, install, and run MRtrix3 on WSL. However, it does come with some drawbacks, notably related to display (mrview and shview). Briefly, the main drawbacks currently are:

  • you will get software-only rendering – no hardware acceleration
  • Volume rendering doesn’t seem to work

The reason for these issues is outlined below, followed by instructions for installation.

Why is display problematic under WSL?

Primarily because WSL is not designed to cater for this: it provides a command-line environment, but no functionality to allow these applications to display. However, due to the way the X11 protocol operates, it is possible to install a third party X server that applications running within WSL can communicate with, allowing them to display their output.

While this works for most X11 (Unix) applications, this doesn’t necessarily extend to the applications included in MRtrix3. The main sticking point is our use of the industry-standard OpenGL version 3.3 API for high performance graphics, which generally expects direct access to the GPU hardware. Unfortunately, under WSL, the same limitations apply as for remote rendering: we don’t have direct access to the hardware, and the GLX extension doesn’t support OpenGL >= 3…

Thankfully, the newest versions of the mesa libraries provide a fully-functional OpenGL 3.3 software renderer, which allow OpenGL 3.3 applications to render to X servers that don’t natively support this. It’s generally pretty finicky to get this to work for remote X11 rendering (although I have seen it work), but with WSL, there are a few configurations that seem to work reliably, which we outline below.

Getting MRtrix3 working on WSL

This should provide you with a working installation of MRtrix3, although as explained above, the graphical applications won’t work yet. To fix this, you’ll need to install an X server. There are a number of options available to you, though not all of them will work, and not all of them are free. These have been tested and seem to work (with the limitations mentioned above):

  • mobaxterm
  • VcXsrv – make sure to start it with ‘native OpenGL’ disabled
  • X410 (available from Microsoft Store, at a price)

Once your X server is installed and running, you will also need to make sure the DISPLAY environment variable is set correctly to allow applications to communicate with it. This should normally do the trick:

export DISPLAY=:0.0

You may want to add this line to your ~/.bashrc or ~/.profile startup files to avoid having to type this in every session.

Finally, you can also install FSL and ANTs in WSL – see each project’s specific instructions on how to do this. Once properly installed and configured, you should have access to all of the functionality in MRtrix3.