Differences between revisions 1 and 83 (spanning 82 versions)
⇤ ← Revision 1 as of 15:07:23 13-08-2012 →
Size: 18433
Editor: MatthewWebster
Comment: Local Merge - 'FslDev'
← Revision 83 as of 15:12:55 22-08-2023 → ⇥
Size: 7662
Editor: MatthewWebster
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
Line 3: Line 4:
We recommend using a UNIX-based computer (such as a Linux PC, Apple or Sun) for carrying out data analysis. However, if this is not available then you can use FSL on a Microsoft Windows computer by running the Linux version of FSL inside a "virtual Linux machine" (a VM), using a freely available program called 'VMware 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. We recommend using Linux or macOS for using FSL. However FSL can be used on Windows via the Windows Subsystem for Linux (WSL, Windows 10 and newer, recommended option) or by running the Linux version of FSL inside a virtual machine (VM).
Line 5: Line 6:
= System Requirements =
 * Windows XP, Vista or 7 (32bit or 64bit)
 * Dual core CPU/ multiple CPU recommended
 * 2GB RAM minimum
 * Minimum 10GB, up to 30GB, of free disc space (VM image expands as necessary up to the 30GB limit)		 = Windows Subsystem for Linux =
Line 11: Line 8:
= Dependencies =
The software package `VMware Player` emulates the core hardware of an x86 machine allowing you to run a second operating system 'in a window'. Virtualisation technology allows the programs running in this VM to achieve speeds approaching that of programs running natively in Windows, as the CPU instruction set doesn't need to be emulated.		 This is the recommended option for using FSL on a Windows computer.
Line 14: Line 10:
The FSL VM (FSLvm) is configured with 1GB of RAM, a virtual hard disk that can grow to 30GB in size, shared (NAT) networking (ie it shares the network connection of your local computer), virtual sound hardware and virtual CD-ROM and floppy drives. We have created an [[https://www.youtube.com/watch?v=QNp3lyP57rw|installation video]] which gives an overview of the installation procedure for the Windows Subsystem for Linux using Windows 10.
Line 16: Line 12:
Before you can run the FSL virtual machine, you need to install a Virtual Machine player package. We support the use of version 3.x of VMware's free [[http://www.vmware.com/products/player/|VMware Player]] software. Download the software from VMware's site and install this package by following VMware's instructions. Once it is installed and your computer has been restarted, launch VMware Player to complete initial setup. == System Requirements ==
Line 18: Line 14:
= The FSL Virtual Machine =
Once VMware Player is installed, download FSLvm from below. The FSLvm is compatible with Windows XP and Windows Vista/7 and is available in two flavours, a 32 bit version for the majority of Windows installations and a 64 bit version for 64 bit Windows Vista/7.		  * Windows 10 or newer. You need to have Windows 10 version 2004 (Build 19041) or higher. You can find out your Windows version / build by opening the '''Settings''' app, and navigating to ''System'' > ''About''.
 * The Windows Subsystem for Linux (WSL) can be installed by following [[https://docs.microsoft.com/en-us/windows/wsl/install|these instructions]]. If you are using an older version of Windows and cannot upgrade, refer to [[https://docs.microsoft.com/en-us/windows/wsl/install-manual|this page]] for installation instructions.
 * Dual core CPU (recommended minmum)
 * 4GB RAM minimum (8GB+ recommended)
 * Minimum 10GB, up to 75GB, of free disk space
Line 21: Line 20:
To find out which version you require see this [[http://support.microsoft.com/default.aspx?scid=kb;en-us;827218|Microsoft document]] '''Follow these steps to install Ubuntu into the Windows Subsystem for Linux:'''
Line 23: Line 22:
||<tableclass="centred" tablestyle="text-align: center;" style="border: none;">[[http://www.fmrib.ox.ac.uk/fsldownloads/FSL_vm5_32.zip|FSLvm [32bit]]]||<style="border: none;">[[http://www.fmrib.ox.ac.uk/fsldownloads/FSL_vm5_64.zip|FSLvm [64bit]]]||

== Verifying the download ==
To confirm that the FSLvm package has downloaded correctly, download the appropriate MD5 hash file below to the same folder you downloaded the FSLvm to and use [[http://www.md5summer.org/|MD5summer]] to check the files.

||<tableclass="centred" tablestyle="text-align: center;" style="border: none;">[[http://www.fmrib.ox.ac.uk/fsldownloads/md5sums/FSL_vm5_32.zip.md5|FSLvm [32bit] MD5 sum]]||<style="border: none;">[[http://www.fmrib.ox.ac.uk/fsldownloads/md5sums/FSL_vm5_64.zip.md5|FSLvm [64bit] MD5 sum]]||

=== Using MD5summer ===
Run md5summer once as an administrator and choose to associate the `.md5` extension with md5summer. Now double click on the downloaded md5 sum file and wait while md5summer checks the file, a green circle to the left of the file name confirms the file's integrity.

= FSLvm Installation =
{{attachment:extract_all_files_vista.jpg|Extract all files|align="right"}}
FSLvm is a fairly minimal install of the CentOS 5 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 all files` in the resulting Windows Explorer window.

The Windows zip expansion wizard will launch. Extract the files to an appropriate location; VMware Player creates a folder in your `Documents` folder called `Virtual Machines` (`My Virtual Machines` under Windows XP) when run for the first time, which is intended for this purpose. Under Windows XP, be sure to create a folder (eg `fsl_vm5_32` or `fsl_vm5_64` as appropriate) to contain the files if you have more than one VM as the Windows XP zip expansion wizard does not preserve the top level folder of the zip archive.

= VMware Player Usage and Configuration =
Detailed VMware Player application usage instructions are available from the VMware Player menu's `Help` entry.
== Initial setup ==
{{attachment:vmx_file.jpg|VMX file icon|align="right"}}Now that the FSLvm is installed, launch VMware Player from the Start menu and click on the `Open` icon. In the `Open` dialogue, browse to the uncompressed FSLvm folder, `fsl_vm5_32` or `fsl_vm5_64` and double click on the `fsl_vm5_32` or `fsl_vm5_64` file within.

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

The first time FSLvm is started VMware 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 like...
{{{
Cannot connect virtual device floppy0. No corresponding device is available on the host. Would you like an attempt to be made to connect the virtual device every time you power on the virtual machine?
}}}
This means that VMware Player cannot locate a floppy disc drive on your computer. Select `No` and you will not be informed of this again. If, instead, it warns you about device `IDE 1:0` then it is unable to find a CD ROM drive. Again choose `No` to dismiss this warning permanently.

The FSLvm will now boot, a process that will take several minutes, don't worry about the `Failed` messages that appear next to the following items (this is normal behaviour):
 * Mounting local filesystems
 * Mounting HGFS shares
 * Mounting other filesystems

Once the boot process has completed, you will be presented with a graphical login screen (initially a textual login screen will appear - wait a little longer for the desktop environment to start). Log in as the user:
{{{
fsl
}}}
with password
{{{
fsluser
}}}
After a few moments you will be presented with the Linux desktop environment.

{{attachment:linux_keyboard.png|Linux keyboard layout configuration|align="right"}}Before continuing, you should take a moment to verify that you have the correct keyboard layout. The FSLvm is configured with a British keyboard; users with a different keyboard layout can change by visiting `System` > `Preferences` > `Keyboard` from the menu at the top of the screen. This will open the keyboard configuration window. Switch to the `Layouts` tab and click the large `+` symbol to add a keyboard layout.

In the windows that appears choose an appropriate layout from the pane on the left (you can drag the divider to see the name of the layout better). Some layouts have alternatives which can be viewed by clicking on the disclosure triangle. However, in most cases the top-level layout will be appropriate. Then select the check box next to your new keyboard layout to make this the default. Finally, deselect `Separate group for each window`.

Once you have the correct keyboard layout, the first task you should undertake is to reset a few passwords to more secure values.

Right click on the desktop and choose `Open Terminal` from the menu. In the terminal window that opens, type the following:
{{{
passwd
}}}
When prompted, enter the current password
{{{
fsluser
}}}
and then enter a new password, twice - choose a secure password (see this [[http://en.wikipedia.org/wiki/Password_strength|Wikipedia]] entry for advice on password selection).

Next you will need to change the password of the `root` user in the FSLvm, do this by issuing the following commands in a terminal window:
{{{
/bin/su -
}}}
Enter the current root password,
{{{
fslroot
}}}
You are now the system Super User. To change this user's password type:
{{{
passwd
}}}
Again, when prompted, enter a new password twice - choose a different secure password.
{{{#!wiki important
'''Important'''

Do not forget these passwords, as you will lose access to FSLvm and all the files stored within it without them.
}}}
Now type:
{{{
exit
}}}
to return to the normal user account.

== Installing FSL ==
You can now install FSL, FSLvm requires the [[http://www.fmrib.ox.ac.uk/fsl/fsldownloads|Linux CentOS5 32bit or CentOS5 64bit]] version depending on whether you are running the 32 or 64 bit VM. See the [[FslInstallation/Linux|Linux installation instructions]] to continue with the installation of FSL. Note that as the FSLvm comes preconfigured for internet access, so the easiest way to continue the install is to follow these instructions with the Firefox web-browser inside the FSLvm.

= 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 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).
 1. VMware Player file sharing
 {{attachment:sharingpane.jpg|Setting up file sharing|align="left"}}File sharing has been configured in the FSLvm to share the entire `C:` drive to the FSLvm. However, due to the potential security risk this poses, VMware Player disables this functionality by default.

 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 Player menu and open the `Shared Folders...` dialogue.

 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.

 {{attachment:browseforfoldertoshare.jpg|Browse to the folder to share|align="right"}}Click on the `OK` buttons to dismiss the dialogues. You should now restart your FSLvm (only necessary the first time you enable sharing) by choosing `System` > `Shutdown` from the top menu bar in the Linux desktop and clicking on the `Reboot` button when prompted on what to do.

 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 `Computer` on the desktop and then, in the resulting window, double click on `Filesystem`. 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.
 {{{#!wiki warning
'''Warning'''

Do not attempt to modify the same files in this shared folder in both operating systems at once - bad things will happen!
}}}
 1. Using external media:
 If you connect a USB storage device whilst VMware 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 ext3 (Linux support only) disk partition or use FAT32 format which can be read on both OSes.
 {{{#!wiki note
'''Note'''

FAT32 is not supported for storing files that you are actively accessing with the FSL tools.		 1. Enable WSL by opening !PowerShell as administrator. Paste this command in and press enter. Follow any prompts given.
  . {{{
wsl --install -d Ubuntu-20.04
Line 139: Line 27:
= 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 [[http://www.chiark.greenend.org.uk/~sgtatham/putty/|puTTY]] (a SSH terminal client).		 2. Restart your computer
Line 142: Line 29:
To identify the IP address of the FSLvm, in a terminal in the FSLvm type:
{{{#!highlight bash numbers=disable
/sbin/ifconfig | grep -C 1 'eth0'		 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 install dc python3 mesa-utils gedit pulseaudio libquadmath0 libgtk2.0-0 firefox libgomp1
Line 146: Line 43:
You are looking for the dotted quartet printed after `inet addr:`.
Line 148: Line 44:
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, choose `System` > `Shutdown` from the Linux desktop menu. Once Linux has shut down VMware Player will exit.		 2. On Windows 10, you need to install a separate application in order to use the FSL user interfaces. We currently recommend installing [[https://sourceforge.net/projects/vcxsrv/files/latest/download|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.
Line 152: Line 46:
= Resetting a hung FSLvm =
If the FSLvm appears to have frozen, you can force a reset by selecting `Reset` from the `Troubleshooting` menu.		 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=\$(grep nameserver /etc/resolv.conf | awk '{print \$2; exit}'):0" >> ~/.bashrc
 echo "export LIBGL_ALWAYS_INDIRECT=0" >> ~/.bashrc
 }}}
 
For Windows 11 you will also need to add run an additional command:
Line 155: Line 54:
= 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.		  {{{
 echo "export LIBGL_ALWAYS_SOFTWARE=1" >> ~/.bashrc
 }}}
Line 158: Line 58:
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. 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''.
Line 160: Line 60:
{{{#!wiki warning
'''Warning about kernel updates'''		 {{{#!wiki caution
If the rule is missing then the process to add a new rule is:
Windows Defender --> Advanced Settings --> Inbound Rules ( left panel ) -> New Rule ( right panel ) —>
Program —> This Program Path ( C:\Program Files\VcXsrv\xlaucnh.exe" --> Next x3 --> Finish ( pick a name like “xlaunch” or “VcXsrv
}}}
Line 163: Line 66:
Any updates listed as `kernel` updates change the core of the operating system, and will result in the accelerated drivers installed in the FSLvm to cease to function. To restore this functionality it is necessary to update the vmware-tools, as this driver package is termed. To do this, log in as the root user and open a terminal window. Within this window type: 5. Use any web browser installed on your Windows computer to get the `fslinstaller.py` script from [[http://fsl.fmrib.ox.ac.uk/fsldownloads|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.
{{{#!wiki caution
FSL must be installed into the WSL file system - do not try and install FSL into a location in your Windows file system. The safest option is to accept the default location, which is ```/usr/local/fsl/```.
}}}

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:
Line 165: Line 86:
vmware-config-tools.pl sudo mkdir /mnt/<usb>
Line 167: Line 88:
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.
Line 169: Line 89:
= Increasing the amount of memory available to FSLvm =
{{attachment:winxp_mem.png|Right click on My Computer and select Properties... Look here for your memory total|align="right"]]The default allocation of 1GB 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. Under Windows XP, open the `Start` menu and right click on `My Computer`. From the pop-up menu choose `Properties` and look in the `Computer information` area, note this value.		 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:
Line 172: Line 91:
Under Vista/7, follow the [[http://windowshelp.microsoft.com/Windows/en-US/help/479a7531-57ad-43c1-91b1-3f46a0e1761e1033.mspx|instructions available on Microsoft's support site]] to find out your total memory capacity. {{{
sudo mount -t drvfs <Letter of USB drive in Windows> /mnt/<usb>
}}}
Line 174: Line 95:
With this in mind, you can calculate the amount of memory you can safely allocate to the FSLvm by following the advice below.
||<tableclass='centred'>Windows XP||Take 1024MB off the value reported||
||Windows Vista||Take 2048MB off the value reported||		 For example, if your USB drive appears as drive E, you would run this:
Line 178: Line 97:
By way of example if you have a Windows 7 computer with 4GB of RAM you can safely increase the FSLvm memory allocation to 2GB. {{{
sudo mount -t drvfs E: /mnt/<usb>
}}}
Line 180: Line 101:
To change the memory allocation of FSLvm, start the VM and then from the VMware Player menu, choose `Change Memory Allocation...` from the `Troubleshoot` sub-menu. In the dialogue that opens type the value you have calculated as being optimal into the memory total box. As indicated in this window once you have clicked `OK` you will need to restart the VM.
{{attachment:vmplayer_tsmenu.png|Opening the Change Memory Allocation dialoge Changing the memory allocation}}
{{attachment:changemem.png|Increasing the amount of disk space available to FSLvm}}		 This mount command will need to be rerun each time you start a new WSL session.
Line 184: Line 103:
Increasing the size of the virtual disk is not possible with the free VMware Player application (it can be done with the commercially available VMware Workstation), 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
 1. Click inside the running VM window so that you are controlling Linux
 1. Connect the USB drive
 1. 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.
 1. Open a terminal and become the root user:
 {{{
su -
== WSL 1 ==

We strongly recommend using WSL 2 over WSL 1. If you have WSL 1, you can update to WSL 2 by opening !PowerShell as administrator, and running these commands:
{{{
wsl --set-default-version 2
wsl --set-version Ubuntu-20.04 2
Line 194: Line 111:
 (enter the root password when prompted)
 {{{#!wiki warning
'''Potential for data loss'''
Line 198: Line 112:
The next step will destroy everything on the drive you specify, so make sure you are certain that this is the correct disk.
If for some reason you are unable to upgrade to WSL 2, you may need to install Xming instead of !VcXsrv. You can download Xming from [[https://sourceforge.net/projects/xming/files/Xming/6.9.0.31/Xming-6-9-0-31-setup.exe/download|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 run this command to add an extra line to your `.bashrc` file:

{{{
echo "export DISPLAY=localhost:0.0" >> ~/.bashrc
Line 200: Line 118:
 1. Run the partitioning tool:
 {{{
parted

= Virtual Machine =

If you are unable to use the Windows Subsystem for Linux (WSL) as outlined above, another option for using FSL on a Windows computer is to use a virtual machine (VM). You can use the freely available [[https://www.virtualbox.org/|VirtualBox]], or [[https://www.vmware.com/uk/products/workstation-pro.html|VMWare Workstation]] if you have a licence.

There are many online tutorials which describe how to install and set up a virtual machine, e.g.:
 * https://www.howtogeek.com/796988/how-to-install-linux-in-virtualbox/
 * https://www.arcserve.com/blog/dead-simple-guide-installing-linux-virtual-machine-windows

FSL can be installed into most modern Linux distributions - we recommend an Ubuntu LTS release, such as 20.04 or 22.04.

Once you have installed a Linux VM, you can install FSL in the same way as for other platforms.

1. Use a web browser '''inside the VM''' to download the `fslinstaller.py` script from [[http://fsl.fmrib.ox.ac.uk/fsldownloads|here]].

2. Open a terminal inside the VM, and run:
   {{{
   cd ~/Downloads
   python fslinstaller.py
   }}}

{{{#!wiki note
Some systems do not have a command called `python`, and will print errors like `python: command not found`. If this happens try calling `python3 fslinstaller.py` or `python2 fslinstaller.py`.
Line 204: Line 143:
 You are now in an interactive partition editor.
 1. 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)
 1.
 {{{
select /dev/sdX
}}}
 (replace X with the letter you determined above)
 1.
 {{{
rm Y
}}}
 where Y is the partition number you noted. Repeat until you have deleted all the partitions on the disk
 1.
 {{{
print
 }}}
 to confirm that they are all gone
 1.
 {{{
mkpart primary 1 ZGB
}}}
 where Z is the size of the disk in question (eg 250GB), hit return to any prompts
 1.
 {{{
quit
}}}
 1. Make a file system on the partition
 {{{
mkfs -t ext3 /dev/sdX
}}}
 (X as above)
 1. 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).

Contents

  1. Introduction
  2. Mac Os X
  3. Linux
  4. Windows

    Contents

    1. Introduction
    2. Windows Subsystem for Linux
      1. System Requirements
      2. Accessing USB drives from Ubuntu
      3. WSL 1
    3. Virtual Machine
  5. Shell Setup

Introduction

We recommend using Linux or macOS for using FSL. However FSL can be used on Windows via the Windows Subsystem for Linux (WSL, Windows 10 and newer, recommended option) or by running the Linux version of FSL inside a virtual machine (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 or newer. You need to have Windows 10 version 2004 (Build 19041) or higher. You can find out your Windows version / build by opening the Settings app, and navigating to System > About.

  • The Windows Subsystem for Linux (WSL) can be installed by following these instructions. 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 Ubuntu into the Windows Subsystem for Linux:

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

  • wsl --install -d Ubuntu-20.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 install dc python3 mesa-utils gedit pulseaudio libquadmath0 libgtk2.0-0 firefox libgomp1

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=\$(grep nameserver /etc/resolv.conf  | awk '{print \$2; exit}'):0" >> ~/.bashrc
 echo "export LIBGL_ALWAYS_INDIRECT=0" >> ~/.bashrc

For Windows 11 you will also need to add run an additional command: 

  •  echo "export LIBGL_ALWAYS_SOFTWARE=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.

If the rule is missing then the process to add a new rule is: Windows Defender --> Advanced Settings --> Inbound Rules ( left panel ) -> New Rule ( right panel ) —> Program —> This Program Path ( C:\Program Files\VcXsrv\xlaucnh.exe" --> Next x3 --> Finish ( pick a name like “xlaunch” or “VcXsrv

5. Use any web browser installed on your Windows 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.

FSL must be installed into the WSL file system - do not try and install FSL into a location in your Windows file system. The safest option is to accept the default location, which is /usr/local/fsl/.

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. If you have WSL 1, you can update to WSL 2 by opening PowerShell as administrator, and running these commands: 

wsl --set-default-version 2
wsl --set-version Ubuntu-20.04 2

If for some reason you are unable to upgrade to WSL 2, you may 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 run this command to add an extra line to your .bashrc file: 

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

Virtual Machine

If you are unable to use the Windows Subsystem for Linux (WSL) as outlined above, another option for using FSL on a Windows computer is to use a virtual machine (VM). You can use the freely available VirtualBox, or VMWare Workstation if you have a licence.

There are many online tutorials which describe how to install and set up a virtual machine, e.g.:

FSL can be installed into most modern Linux distributions - we recommend an Ubuntu LTS release, such as 20.04 or 22.04.

Once you have installed a Linux VM, you can install FSL in the same way as for other platforms.

1. Use a web browser inside the VM to download the fslinstaller.py script from here.

2. Open a terminal inside the VM, and run: 

  •    cd ~/Downloads
   python fslinstaller.py

Some systems do not have a command called python, and will print errors like python: command not found. If this happens try calling python3 fslinstaller.py or python2 fslinstaller.py.

 

FslInstallation/Windows (last edited 11:02:08 30-08-2023 by MatthewWebster)