Installation on Windows

We recommend using Linux or macOS for using FSL. However FSL can be used on Windows via the Windows Subsystem for Linux (WSL, recommended) or by running the Linux version of FSL inside a virtual machine (VM).

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.
Dual core CPU (recommended minmum)
8GB RAM minimum (16GB+ recommended)
Minimum 20GB of free disk space

Warning

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 in your WSL home directory at /home/<wsl-user>/fsl/ (where <wsl-user> is the WSL user account that you created when you set up WSL).

Install WSL / Ubuntu

Follow these steps to install a WSL Ubuntu Linux system within Windows. The remainder of these instructions assume that you are installing Ubuntu, but advanced users may wish to install a different flavour of Linux.

Open a Windows PowerShell (as administrator) window, copy+paste these commands into the PowerShell, press enter, and follow any prompts given:
```
wsl --update
wsl --shutdown
wsl --set-default-version 2
wsl --install -d Ubuntu-22.04
```

If you experience any problems, consult the Microsoft WSL documentation.

Restart your computer.
Start the Ubuntu application to open an Ubuntu terminal (also known as a shell).
Set up a username and password for Ubuntu - this only needs to be done the first time you start Ubuntu. This can be different from your Windows username/password. Make sure you remember your username and password, as you will need it later on.

Install FSL dependencies

Some system dependencies need to be installed into Ubuntu before FSL can be installed. Copy+paste these commands into the Ubuntu terminal to install these dependencies. You may be prompted for a password - enter the password that you set up earlier:

sudo apt update
sudo apt -y upgrade
sudo apt-get install dc python3 bzip2 mesa-utils gedit firefox libgomp1

Install FSL

For new users, we recommend using the getfsl.sh script to install FSL:

Open a terminal.
On Linux, you should be able to find a Terminal application in your system/application menu.
On macOS, you can find the Terminal app via Finder, by navigating to Applications > Utilities.
On Windows, open the WSL distribution, (e.g. the Ubuntu app, if you chose to install Ubuntu).
Copy and paste the following command into the terminal, and push enter:

curl -Ls https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/getfsl.sh | sh -s

Or download the getfsl.sh script, and run sh ~/Downloads/getfsl.sh in your terminal.

Wait for the installation to complete - if you have a fast internet connection, installation should take around 10-15 minutes. If your internet connection is slower, please be patient.
Once the installation has finished, close and re-open your terminal window.

The installation script will print out a number of messages, reporting its progress, and any errors that may arise.

Please read the output carefully - the following message will be printed when the installation has completed successfully:

FSL successfully installed

If you do not see this message: - Save a copy of all of the text that the installer printed to the terminal - Search in your home directory for a file called fsl_installation_<date>.log (where <date> is a series of numbers representing the current date. - Check the troubleshooting page for some potential solutions. - Send us a message with the above information, and we will try our best to help.

Otherwise, you can verify your installation to make sure that the installation has succeeded.

Installing optional components

FSL 6.0.7.13 and newer may contain additional optional components - for example, - the TRUENET deep learning segmentation tool - the osl-dynamics dynamic functional connectivity toolbox

If you wish to install these components, use the --extra option when running the getfsl.sh script. You also need to specify the FSL installation location (e.g. ~/fsl/), for example:

curl -Ls https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/getfsl.sh | sh -s -- ~/fsl/ --extra truenet

or

curl -Ls https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/releases/getfsl.sh | sh -s -- ~/fsl/ --extra osl-dynamics

Custom/advanced installations

If you need to customise any aspects of the installation, instead of using getfsl.sh, we recommend downloading and running the fslinstaller.py script. This is a Python script which can be executed with any verison of Python 2.7 or newer. You can run the fslinstaller.py script like so:

python fslinstaller.py

And you can read about the available options by running:

python fslinstaller.py --help

Python is required

Your system must have a Python interpreter installed before you can run the fslinstaller.py script. 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.

Some versions of macOS do not have Python installed by default - if you do not have any Python command available, you can download an installer from https://www.python.org. Alternately, Python will be installed as part of Xcode, which you can install by running sudo xcode-select --install.

If you experience SSL certificate errors on macOS, try running the installer with /usr/bin/python fslinstaller.py or /usr/bin/python3 fslinstaller.py. If you have installed Python separately from https://www.python.org, make sure you have run the Install certificates script, as described here.

Do not install FSL onto a USB drive

FSL can only be installed onto file systems which support symbolic links and hard links - this does not include the FAT32 file system, which is used on many USB drives, so you are likely to encounter issues if you try to install FSL onto a USB drive.

By default, FSL is installed into your user account home directory (at ~/fsl/), and so does not require administrative privileges. You can specify a different location (e.g. /usr/local/fsl/) when running the fslinstaller.py script like so:

python fslinstaller.py -d /usr/local/fsl/

If you choose to install FSL to a different location, or are installing FSL on a multi-user system, you may need to enter your administrator password before the installation can proceed. You can run the fslinstaller.py script as described above - you will be prompted for your password when necessary.

For single-user installations, we recommend that you do not use sudo when running the fslinstaller.py script. Instead, run the script as your normal user - you will be prompted for your root password as needed.

If you do not have permission to use sudo then the installer will fail and you will need to either install into a folder belonging to your user or to run the installer as the root user. If you run the fslinstaller.py script with sudo, or as the root user, see the FSL configuration page for details on how to setup your user account for FSL.

Allocate enough RAM

This step is only required if you are using a computer with 8GB or less of RAM.

If you are using a computer with 8GB or less of RAM, you may need to perform some additional steps to ensure that enough RAM is allocated to the WSL subsystem.

Open a Windows PowerShell (as administrator) window, and type:
```
 wsl --shutdown
 notepad "$env:USERPROFILE/.wslconfig"
```
Notepad should open up a file named .wslconfig - enter the following lines into the file, and save it:
```
 [wsl2]
 memory=6GB # Limits VM memory to 6GB
```
Restart WSL/Ubuntu and confirm that the available RAM has increased by running this command:
```
 free -mh
```
Due to how WSL2 works, you must close WSL (by running wsl --shutdown in a PowerShell window) between uses of FSL, to ensure RAM is freed up for your Windows sessions. You may also wish to change the memory value in the .wslconfig file, e.g. to memory=4GB, if you experience degraded performance when using Windows applications.

Install an X server

This step is only required if you are using WSL1, or installing an old version of FSL (6.0.7.11 or older).

If you are using WSL version 1, or installing an older version of FSL, you need to install a separate application, called a X11 server, in order to use graphical FSL programs. We currently recommend installing VcXsrv, although several alternatives are available, including MobaXterm and Xming.

If you are using WSL2, you need to disable the built-in GUI server - you can do this as follows:

Open a Windows PowerShell (as administrator) window, and type:
```
 wsl --shutdown
 notepad "$env:USERPROFILE/.wslconfig"
```
In the Notepad window, enter the following text, and save the file. If [wsl2] is already present, don't add it again - just add guiApplications=false line underneath [wsl2]:
```
 [wsl2]
 guiApplications=false
```

Now, to install VcXsrv:

Download and run the installer from https://sourceforge.net/projects/vcxsrv/. This will install an application called XLaunch.
In order for VcXsrv to work, you will need to modify your Ubuntu configuration profile. If you are using WSL1, copy+paste the following code into the Ubuntu shell:
```
echo "export DISPLAY=:0" >> ~/.bashrc
```

Or, if you are using WSL2, copy+paste the following code into the Ubuntu shell:

    echo "export DISPLAY=\$(grep nameserver /etc/resolv.conf  | awk '{print \$2; exit}'):0" >> ~/.bashrc
    echo "export LIBGL_ALWAYS_INDIRECT=1" >> ~/.bashrc

Start the XLaunch app. You need to make sure that Native OpenGL is deselected, and Disable access control is selected, in the Extra > Settings panel.
Type glxgears into the Ubuntu shell, and press enter . A window with three spinning gears should open.

If glxgears 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.

You must start XLaunch before running any graphical applications (including FSLeyes). Alternatively, follow these steps to configure XLaunch to start automatically whenever you turn on your computer:

Start the XLaunch app as described above. On the final window, click on the Save configuration button, and save the configuration file to Documents/config.xlaunch.
Open the Run command prompt by holding down the Windows key and pressing R (Win+R). Type in shell:startup, and push enter. This will open your startup folder in an Explorer window.
Open a second Explorer window and navigate to your Documents folder.
Drag and drop (or copy and paste) the config.xlaunch file from your Documents folder into the startup folder.

After following these steps, XLaunch should start automatically whenever you turn on your computer.

Info

If you have a high-DPI display, you may need to perform some additional steps to ensure that Linux applications are displayed at the correct resolution. This StackExchange post has some useful pointers on setting up your system.

Installing FSL into a virtual machine (VM) instead of WSL

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 license.

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 - make sure you are using a terminal/web browser inside the VM when downloading and running the getfsl.sh/fslinstaller.py scripts.