Where can I find help, tutorials or papers about FSL?

Every installation of FSL comes with html documentation in $FSLDIR/doc In addition, there are general FSL web pages, including some documentation and related references, at

A tutorial-based set of lecture slides and practicals can be found at and is related to the content of the FSL/Freesurfer course which is held once or twice each year - see for details on upcoming/recent courses.

Further help can also be obtained via the public FSL email list. Note that you must join the list in order to post questions.

Finally, detailed technical reports can be found at and a full list of conference and journal papers produced by the FMRIB Analysis Group can be found at

How do I best report problems to the FSL email list?

In order to understand and analyse problems please provide the following pieces of information:

In the case of FEAT / MELODIC problems, please check the log (report.log/melodic.log) files first, e.g. you might be out of space or certain files might actually not be readable.

Please make sure that the data is not corrupted: check your input data by loading it into fslview (or slices). If your input data is not what you expect, try and fix this first. You can also obtain useful header information with fslhd filename and useful information about the image intensity range from fslstats -r -R. If you need to report a problem, please provide this information in an email.

Please attach the entire output of this command to your email. Note that the output is written to a file in /tmp (filename is given at the end of the output message) for convenience in attaching it to an email. Also, please be as specific as possible about command line error messages.

NOTE: Please do not send Analyze/NIFTI files (AVW/NII) to the email list; If these are needed to resolve the problem, place them somewhere to download!

What image format does FSL need?

FSL programs expect to read NIFTI-1 format images. These files can be read and written in compressed (gzip format) or uncompressed form. To convert between these different formats, use the fslchfiletype utility or the environment variable FSLOUTPUTTYPE. These are described more fully in the nifti1 page.

An image can be 2D or 3D or 4D (multiple time points).

FSL programs for FMRI analysis use single 4D NIFTI images, not lots of 3D images (such as SPM does).

You will need some other program to convert between formats (e.g. DICOM). A list of such converters can be found at:

How do I convert between 3D and 4D NIFTI images?

In order to convert between multiple 3D and single 4D images, use the following programs (found in $FSLDIR/bin):

3D -> 4D

note that if your 3D files have numbers that are zero padded (eg in0001 etc.) then you can do this more easily. For example, with Analyze files:

In general, due to the multiple file formats, we recommend using the utility imglob for getting filenames. For example:

(NB: the above command contains backquotes, not forward quotes)

4D -> 3D

this program automatically chooses the output name.

How can I modify the orientation of my data?

Please look at the "Orientation-related Utilities" section of the FSLUTILS documentation page.

How do I know right from left in the images?

Look at the labels in FSLView. For more information about orientation, the NIfTI format and FSLView display, see the "Orientation-related Utilities" and "Background information on NIfTI Orientation" sections of the FSLUTILS documentation page.

How do I run the GUIs or command lines?

On most machines the GUIs can be run by:

However, under MacOSX the GUIs are run by:

On all machines, the command line versions can be run by typing the name of the program, all in lower case: e.g. flirt Note: with no arguments the command line versions return a help statement that includes usage lines and available options.

How do I get my command line to run?

Many things might be the cause of this, but the following list covers the vast majority of problems:

How can I make old scripts work with FSL>=3.2?

Due to the use of new file formats, with different extensions, most scripts need some modification to work fully with FSL>=3.2. However, the changes are relatively straightforward and are described in a separate scripting page.


How do I install (or compile) FSL?

Instructions on downloading and installing FSL can be found at: Instructions on compiling FSL can be found at:

Note the special instructions for installing on MacOSX and Windows.

Note that you must set up the environment variable FSLDIR to point to the directory where FSL is installed on your machine. It is also necessary to source a setup file. This can be done by:

Also, you would normally want to include $FSLDIR/bin in your PATH. In general these are best done in your shell startup file (e.g. .bashrc or .profile). The syntax required depends on the shell you use, but is normally either one of the following (where /usr/local/fsl is used as an example for the installation location):

What sort of system requirements does FSL have?

FSL is supported on the following hardware: Linux, Mac, Windows running a Linux Virtual Machine. FSL is supported for the following operating systems: Linux (Cent OS 4 and 5, Debian/Ubuntu), MacOS X 10.5 and 10.6, Windows XP (with VMplayer)

Note: that FSL also works with other flavours of Linux such as SuSE - although they may need to be built from source rather than using the precompiled Cent OS binaries.

It is recommended that the following memory and disk requirements are met:

Be warned that too little swap space causes "unexplained" crashes!

How can I test if my installation works?

Download and run the FSL Evaluation and Example Data Suite (FEEDS). See also: How do I get and run FEEDS?

How do I get and run FEEDS?

Information on how to run the FSL Evaluation and Example Data Suite (useful for testing that your installation is working and to get a benchmark for speed) can be found at:

This site includes a link to the download URL at:

A timing table using FEEDS as a benchmark for comparing relative performance between machines can be found at:

Why does an FSL program crash when it is trying to process a very large dataset?

Certain programs in FSL can require a large amount of memory (RAM) to run, depending on the size of the data that you are trying to analyse. For example:

The memory available to a program depends on how much physical RAM you have on your computer, what other programs are already running, and how much "virtual memory" (swap) you have configured. Swap is hard disk space that is used to act as additional memory on top of your actual memory, allowing programs larger than your physical memory to run, but much more slowly. Hence, if your program is running out of memory you should consider increasing your physcial RAM and/or your swap space (the latter is cheaper but a slower solution). Your local sysadmin can easily increase swap space if you have spare hard disk space available.

However, there is one further caveat. On 32-bit computers there is a limit on the size that a single program can be, regardless of how much RAM/swap you have. This limit is normally 2GB. The best solution to this is to move to a 64-bit computer (for example, all Apple computers are now 64-bit, and it is easy to find cheap 64-bit PCs to install 64-bit Linux on). On a 64-bit computer, as long as you have enough RAM/swap, there is effectively no limit to the size of the programs that you can run.



FSL FAQ (last edited 10:06:56 29-10-2013 by MatthewWebster)