Introduction

We recommend using a UNIX-based computer (such as a Linux PC or Apple OS X) for carrying out data analysis. However FSL can be used on Windows via the Windows Subsystem for Linux (WSL, Windows 10 only, recommended option) or by running the Linux version of FSL inside a "virtual Linux machine" (a VM).

Windows Subsystem for Linux

This is the recommended option for using FSL on a Windows computer.

We have created an installation video which gives an overview of the installation procedure for the Windows Subsystem for Linux using Windows 10.

System Requirements

• Windows 10

• The Windows Subsystem for Linux (WSL) can be installed by following these instructions. You need to have Windows 10 version 2004 and higher (Build 19041 and higher). If you are using an older version of Windows and cannot upgrade, refer to this page for installation instructions.

• Dual core CPU (recommended minmum)
• 4GB RAM minimum (8GB+ recommended)
• Minimum 10GB, up to 75GB, of free disk space

Follow these steps to install the Ubuntu subsystem in Windows:

1. Enable WSL by opening PowerShell as administrator. Paste this command in and press enter. Follow any prompts given.

• wsl --install -d Ubuntu-18.04

2. Restart your computer

3. Start the "Ubuntu" app to open an Ubuntu shell.

4. Set up a username and password for Ubuntu (only necessary the first time you launch it)

Now follow these steps to install FSL into your Ubuntu machine:

1. Copy+paste these commands into the Ubuntu shell to install a few FSL dependencies:

• sudo apt update
  sudo apt -y upgrade
  sudo apt-get install dc python mesa-utils gedit pulseaudio libquadmath0 libgtk2.0-0 firefox

2. On Windows 10, you need to install a separate application in order to use the FSL user interfaces. We currently recommend installing VcXsrv - this will install an application called XLaunch. When running XLaunch, it is critical to deselect Native OpenGL and select Disable access control in the Extra Settings panel. You need to start the XLaunch app in order for graphical applications in Ubuntu to work.

3. In order for VcXsrv to work, you will need to add these lines to your .bashrc file. Copy+paste the following lines into the Ubuntu shell:

•  echo "export DISPLAY=\$(ip route | awk '/default via / {print \$3; exit}' 2>/dev/null):0" >> .bashrc
   echo "export LIBGL_ALWAYS_INDIRECT=1" >> .bashrc

4. Try running glxgears. A window with three spinning gears should open. If this doesn't work, it is possible that Windows Defender Firewall has blocked the VcXsrv process. Go to Control panel > System and security > Windows defender firewall > Advanced settings > Inbound rules and make sure that the VcXsrv rules are not set to block - if they are you will need to edit the VcXsrv rule and change it from block to allow.

5. Use any web browser installed on your Windows 10 computer to get the fslinstaller.py script from here. Download it to your Downloads folder. When selecting the OS to install on the download page, it is important to choose Ubuntu ( the Linux version installed by WSL ) and not Windows, or you will be directed to the VM instead of the installer script.

6. Run the fslinstaller.py script in the Ubuntu shell with this command. Replace <WindowsUserName> with your Windows account username:

•  python "/mnt/c/Users/<WindowsUserName>/Downloads/fslinstaller.py"

  Say yes to all default install options. The installation can take some time, so please be patient, and do not abort the installation.

7. Close and re-open the Ubuntu shell.

8. try running the fslmaths, fsl, and fsleyes commands.

Accessing USB drives from Ubuntu

If you want to mount other folders or drives ( e.g USB drives), create a directory in your Ubuntu file system where the drive will be mounted - replace <usb> with a name of your choosing:

sudo mkdir /mnt/<usb>

Now mount the USB drive with this command, replacing <Letter of USB drive in Windows> with the letter that the USB drive appears as in Windows:

sudo mount -t drvfs <Letter of USB drive in Windows> /mnt/<usb>

For example, if your USB drive appears as drive E, you would run this:

sudo mount -t drvfs E: /mnt/<usb>

This mount command will need to be rerun each time you start a new WSL session.

WSL 1

We strongly recommend using WSL 2 over WSL 1 - on WSL 1, the fslinstaller.py script may not complete successfully, and you may see a message like Failed to create FSL Python environment.

If this happens for you, the best option is to update to WSL 2 by opening PowerShell as administrator, and running these commands:

wsl --set-default-version 2
wsl --set-version Ubuntu-18.04 2

Then open an Ubuntu shell, and run these commands:

sudo rm -r $FSLDIR/fslpython
sudo $FSLDIR/etc/fslconf/fslpython_install.sh -f $FSLDIR

If for some reason you are unable to use WSL 2, open an Ubuntu shell, and run these commands instead:

sudo rm -r $FSLDIR/fslpython
sudo wget -O $FSLDIR/etc/fslconf/fslpython_install.sh "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation/Windows?action=AttachFile&do=get&target=fslpython_install.sh"
sudo $FSLDIR/etc/fslconf/fslpython_install.sh -f $FSLDIR

If you stick with WSL 1, you may also need to install Xming instead of VcXsrv. You can download Xming from here. You will need to have Xming running in windows, before any linux GUIs will work. If you decide to use Xming, you will need to add the following line to your .bashrc file:

DISPLAY=localhost:0.0

This change can be made via notepad if you run:

notepad.exe ~/.bashrc

in the Ubuntu shell and add the line to end of the file. Alternatively you can run this command in the Ubuntu shell:

echo "export DISPLAY=localhost:0.0" >> ~/.bashrc

Virtual Machine

The VM option requires a freely available program (free for non-commercial use only) called 'VMware Workstation Player' by VMware. This is fairly easy to setup, and we provide basic installation instructions below, but please note that we cannot in general offer further help for the setup and maintenance of the virtual machine itself - we just offer support on the running of FSL within it.

System Requirements

• Windows 7,8,10
• Dual core CPU (recommended minmum)
• 4GB RAM minimum (8GB+ recommended)
• Minimum 10GB, up to 75GB, of free disk space (VM image expands as necessary up to the 75GB limit, if used)

The FSL VM (FSLvm) is configured with 2GB of RAM, a virtual hard disk that can grow to 75GB in size, shared (NAT) networking (ie it shares the network connection of your local computer), virtual sound hardware and virtual CD/DVD drive.

Before you can run the FSL virtual machine, you need to install a Virtual Machine player package. We support the use of version 12+ of VMware's free* VMware Workstation Player software. Download the software from VMware's site and install this package by following VMware's instructions (or you can look at videos on youtube if you get stuck). Once it is installed and your computer has been restarted, launch VMware Workstation Player to complete initial setup.

The FSL Virtual Machine

Once VMware Player is installed, download FSLvm from below. The FSLvm is compatible with Windows 7/8 and 10 and is 64 bit, so requires a 64 bit CPU. See http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1003945 for information on how to check that your computer will be able to run the FSLvm.

Verifying the download

If you want to confirm that the FSLvm package has downloaded correctly please see this page.

FSLvm Installation

FSLvm is a fairly minimal install of the CentOS 7 Linux distribution and is provided as a zip file. To install, decompress the downloaded FSLvm by double clicking on the zip file and clicking on Extract button in the Windows Explorer toolbar. Choose to extract all files, then choose a location to extract to. By default it will extract to a folder 'FSLVm7_64', remove this from the end of the expansion location so that an unnecessary 'FSLVm7_64' folder is not created.

VMware Workstation Player Usage and Configuration

Detailed VMware Workstation Player application usage instructions are available from the VMware Player menu's Help entry.

Initial setup

Now that the FSLvm is installed, launch VMware Workstation Player from the Start menu and click on the Open icon. In the Open dialogue, browse to the uncompressed FSLvm folder, FSLVm7_64.vmware and double click on the FSLVm7_64 file within.

Subsequent to the initial launch, the FSLvm will appear in the list of Recent Virtual Machines allowing quick launching.

During the launch of a VM you may be prompted to download and upgrade the VMware Tools (updates for these appear periodically).

You should agree to this.

The first time FSLvm is started VMware Workstation Player will ask if the VM was moved or copied, choose I copied it (this sets up the network correctly).

Depending on your Windows computer's hardware, you may also receive additional messages about missing hardware. These can be dismissed.

The FSLvm will now boot, a process that may take several minutes.

Once the boot process has completed, you will be automatically logged into the account fsluser and the installation of FSL will begin. You will be prompted to choose a password for this account, make a note of this password as you will need it to use the 'sudo' command when you install FSL updates. Next FSL will be downloaded, installed and configured. Finally, the virtual machine will check for pending software updates, install them and reboot, please be patient this final step may take a while.

At this point the installation is complete. Read on if you want to find out how to modify the VM's settings to suit your keyboard layout, to enable file sharing and to increase the memory available to the VM.

Further steps

The FSLvm is configured with a British keyboard; users with a different keyboard layout can change by clicking on the power symbol in the top right of the screen and clicking on the tools icon in the bottom left of the resulting window.

Click on the Region & Language icon in the settings window.

The Input Sources at the bottom of the window allow the addition of different keyboard layouts.

Accessing your Windows files

There are four options for transferring/accessing files stored on your Windows disk into the FSLvm, presented in order of ease of use:

1. Drag-and-drop

   • The VMware Workstation Player application supports the dragging and dropping of files from Windows into the FSLvm. To transfer files select them in the Windows Explorer and then drag them into your FSLvm window and drop in the folder you would like it to reside in (or onto the Desktop). You may find that the first attempt to copy a file results in an error, click Retry which should complete. Subsequent drags/drops should then be fine.

2. VMware Workstation Player file sharing

   Before changing the sharing settings first create a folder to share. Put this folder somewhere appropriate in your home folder. To enable sharing and to point it to this new folder, start up the FSLvm and visit the VMware Workstation Player menu and open the Shared Folders... wizard. To enable sharing permanently select the Always Enabled radio button. Now select the pre-configured share and click on the Properties button. This will open another dialogue box allowing you to change the name the share will appear as in Linux and to change the Windows file path for the shared folder. Click on the Browse button and locate the folder you created earlier. Click on the OK buttons to dismiss the dialogues. You may now access files held within this shared folder through the path /mnt/hgfs. To navigate there through the graphical file browser, double click on Home on the desktop and then, in the resulting window, click on Computer. This will open a folder showing the folder / from where you can navigate to mnt and then hgfs. Within here will be the shared folder, named as specified in the Shared Folders dialogue. See below for help if the shared folders function stops working.

   Warning

   Do not attempt to modify the same files in this shared folder in both operating systems at once - bad things will happen!

3. Using external media: If you connect a USB storage device whilst VMware Workstation Player is running and has the input focus it will allow Linux to see the storage device. In most cases it will automatically mount and an icon will appear on the Linux desktop. Linux has read-only support for NTFS, so you will need to create an ext4 (Linux support only) disk partition or use FAT32 format which can be read on both OSes.

Accessing ExFAT USB drives from the VM

If you wish to use an ExFAT-formatted USB drive, you will need to install an ExFAT driver into the virtual machine. Open a terminal and run these commands:

sudo yum -y install epel-release
sudo rpm -Uvh http://li.nux.ro/download/nux/dextop/el7/x86_64/nux-dextop-release-0-5.el7.nux.noarch.rpm
sudo yum install exfat-utils fuse-exfat

Network access

The FSLvm is configured to share your network connection, and so has full access to any networks that your Windows computer can see. You can also access your FSLvm from Windows over this internal network with tools like puTTY (a SSH terminal client).

To identify the IP address of the FSLvm, in a terminal in the FSLvm type:

/sbin/ifconfig | grep -C 1 'eth0'

You are looking for the dotted quartet printed after inet addr:.

Connection to the host is now possible using this address as the hostname to connect to within puTTY.

Shutting down

Under normal circumstances you should just close the FSLvm window, this will suspend the FSLvm to disk allowing quick restoration of your session at a later date. However, sometimes it may be necessary to shutdown the FSLvm entirely (say if you are moving it to a new computer). To do this, click on the power icon in the top right of the desktop menu bar, click on the power icon (bottom left) and choose Shutdown. Once Linux has shut down VMware Workstation Player will exit.

Resetting a hung FSLvm

If the FSLvm appears to have frozen, you can force a reset by selecting Reset from the Troubleshooting menu.

Updating the FSLvm

From time to time the Linux vendor will issue security updates which in general should be installed to keep the FSLvm secure.

When updates are available a message window will appear in the top right of the Linux desktop advising you of what updated packages are available. Clicking on the icon associated with this message will open the package update utility which can be used to update the system. You will be asked for the root password that you set when installing the FSLvm before being allowed to install these updates.

Updating VMware Tools

If you find that the shared folder functionality stops working then you will need to update the VMware tools, to do this follow these instructions.

To update the tools choose Manage > Reinstall VMware Tools from the VMware Workstation Player menu, wait 30 seconds then open a terminal window in the FSLvm. Within this window type:

cd /tmp
tar xf /media/VMware\ Tools/VMwareTools-*.tar.gz
cd vmware-tools-distrib
sudo ./vmware-config-tools.pl

Enter your account password when requested.

You will now be asked a series of questions. Hit return to accept the default to all of the questions. Once the installation is complete you should reboot the FSLvm to allow the changes to take effect.

Increasing the amount of memory available to FSLvm

Right click on My Computer in the Start menu and select Properties... the window that opens will tell you how much your computer has. The default allocation of 2GB is only suitable for light use of the FSL software suite. For more demanding analyses you will need to increase the amount of available memory allocated to the virtual machine. Before you change this setting you should find out how much memory your computer has.

With this in mind, you can calculate the amount of memory you can safely allocate to the FSLvm by following the advice below.

By way of example if you have a Windows 7 computer with 8GB of RAM you can safely increase the FSLvm memory allocation to 6GB.

To change the memory allocation of FSLvm, start the VM and then from the VMware Player menu, choose Manage > Virtual Machine Settings.... In the dialogue that opens type the value you have calculated as being optimal into the memory total box - the memory section will suggest some values for you. As indicated in this window once you have clicked OK you will need to restart the VM.

Increasing the size of the virtual disk is also possible, but not straightforward, so if you require additional disk space we would recommend adding an additional USB hard drive to your system and dedicating it's use to Linux. For correct FSL operation, the drive should be formatted with the Linux ext3 filesystem. Follow these steps to carry out this formatting process.

1. Start with the drive disconnected
2. Click inside the running VM window so that you are controlling Linux
3. Connect the USB drive

4. If the drive mounts and appears on your Linux desktop, right click and choose to un-mount it. Most probably you will have a drive formatted as NTFS, so you may see this warning that Linux Cannot mount volume - Click OK. Unfortunately, Centos won't let you format the device at this point, so you need to format via the command line.

5. Open a terminal and become the root user:

   su -

   • (enter the root password when prompted)

   Potential for data loss

   The next step will destroy everything on the drive you specify, so make sure you are certain that this is the correct disk.

6. Run the partitioning tool:

   parted

   • You are now in an interactive partition editor.
7. Find your disk:

   print all

   Locate your external drive (look for the Model: entry that matches your disk) and note down the Disk field (/dev/sdX) (this will probably be /dev/sdb) and the numbers of any existing partition number(s)

8. select /dev/sdX

   • (replace X with the letter you determined above)

9. rm Y

   • where Y is the partition number you noted. Repeat until you have deleted all the partitions on the disk

10. print

    • to confirm that they are all gone

11. mkpart primary 1 ZGB

    • where Z is the size of the disk in question (eg 250GB), hit return to any prompts

12. quit

13. Make a file system on the partition

    mkfs -t ext4 /dev/sdX

    • (X as above)

14. Disconnect the drive and reconnect it and it should automatically mount. Open Computer on your desktop and you should see the drive, and it can be accessed at /media/disk (or some variant on that).