Install FSL with conda

Conda is a platform-agnostic environment and package manager - conda can be used to create isolated environments on your file system, with each environment containing a different collection of software packages. All of the components that make up FSL are published as conda packages, so it is possible to install FSL software using conda, instead of using the getfsl.sh or fslinstaller.py scripts. This page contains an overview of conda and associated terminology, and some examples on how to use conda to install parts of FSL.

Conda is a very powerful tool with many options, and extensive documentation - if you want to learn more, the Getting started section of the conda documentation is a good starting point.

Depending on when you installed FSL, your installation may be based on mamba or micromamba instead of conda. These are alternative conda implementations which, for the most part, are functionally identical to conda. However, you may need to adapt the instructions on this page depending on whether you are using conda, mamba, or micromamba (or some other implementation of conda).

To create a conda environment containing fslmaths, you can use a command such as:

conda create                                                  \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
  -c conda-forge                                              \
  -n fslmaths-env                                             \
  fsl-avwutils

where: - -c <name-or-url> tells conda where to download packages from - -n fslmaths-env tells conda to create an environment named fslmaths-env - fsl-avwutils is the name of the conda package that provides the fslmaths command.

If you have installed FSL 6.0.6 or newer, then you can use its conda command to create an environment - for example:

$FSLDIR/bin/conda create                                      \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
  -c conda-forge                                              \
  -n fslmaths-env                                             \
  fsl-avwutils

Then you can activate this environment, and configure your shell session to use this new partial FSL installation like so (see below for more details on activating conda environments):

source $FSLDIR/bin/activate fslmaths-env
export FSLDIR=$CONDA_PREFIX
source $FSLDIR/etc/fslconf/fsl.sh

The above commands assume that you have permission to write to the $FSLDIR directory - recent FSL versions will be installed to ~/fsl/ by default, so this will hopefully not be a problem.

If you do not have permission to write to your $FSLDIR directory (or more generally, if you experience permission errors when trying to create a conda environment), you may need to configure conda to use a different location for its environment and package cache. You can do this by creating a file called ~/.condarc which contains (for example):
envs_dirs:
  - ~/.conda/envs
pkgs_dirs:
  - ~/.conda/pkgs

Installing `conda`

FSL 6.0.6 and newer are based on conda, so if you have FSL installed, you can simply use $FSLDIR/bin/conda or $FSLDIR/bin/mamba to create environments and install packages.

Tip

While it is possible to install additional packages into your FSL installation, we recommend using separate conda environemnts - installing packages into an existing conda environment can cause already-installed packages to be updated, which could cause some FSL tools to break.

If you don't have FSL, or are working in an environment with limited resources (e.g. a cloud instance or Docker/Singularity container), there are a number of methods of installing conda:

Anaconda distribution: This is a conda installation which comes with a wide range of software packages pre-installed
Miniconda: This is a minimal command-line-based conda installation
Miniforge: This is version of Miniconda which is customised to source packages from conda-forge instead of the main anaconda channels (see below for some more details on conda channels).

There is an alternative to conda called mamba, which is a faster C++ re-implementation of conda. If you have mamba available, you can usually use it in place of conda, simply by substituting the conda command for mamba. You can install mamba instead of conda with one of the following options:

Mambaforge is a version of Miniforge which includes mamba
Micromamba is a minimal mamba implementation (a single file binary). It is particularly useful for acquiring a conda implementation within automated cloud or CI environments.

After you have installed conda through one of the above methods, you need to make sure that the conda (or mamba or micromamba) executable is available via your $PATH environment variable. For example, if you have installed Miniconda, and accepted the default installation location, you can make conda available by running this command, or adding it to your shell profile:

export PATH=~/miniconda3/bin::$PATH

Alternatively, the conda installer may offer to modify your shell profile, so that it is always available. Refer to the documentation for the conda variant that you have selected.

Conda environments

A conda environment is a directory on your file system which contains a collection of installed conda packages. You can create an environment with the conda create sub-command. For example, to create a conda environment containing fslmaths, you can use this command:

conda create                                                  \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
  -c conda-forge                                              \
  -n fslmaths-env                                             \
  fsl-avwutils

This will create a conda environment named fslmaths-env, which contains the fsl-avwutils package (this is the name of the package that provides the fslmaths executable).

Using the -n <environment-name> option will cause your environment to be created in a centralised location on your file system, typically <conda-installation-location>/envs/<environment-name>. For example, if you have installed conda to ~/miniconda3/, the command above will create your environment at ~/miniconda3/envs/fslmaths-env/.

It is also possible to create a conda environment in a specific location on your file system by using the -p option. For example, this command will create an environment at ~/fslmaths-env/:

conda create                                                  \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
  -c conda-forge                                              \
  -p ~/fslmaths-env                                           \
  fsl-avwutils

In order to use the software installed in a conda environment, you need to activate it. Activating an environment simply modifies your shell environment (e.g. your $PATH variable) so that the executables and libraries contained in the environment are available in your terminal session. When you activate a conda environment, you need to refer to it either by its name (if you created it with the -n option), or by its location on the file system (if you created it with the -p option).

Depending on how you have installed conda, you can activate an environment using one of the following methods:

If you have allowed conda to modify your shell profile, you can activate an environment with the conda activate sub-command - if you created your environment with -n fslmaths-env:
```
conda activate fslmaths-env
```
or if you created your environment with -p ~/fslmaths-env:
```
conda activate ~/fslmaths-env
```
If you have instead added the <conda-installation>/bin/ directory to your $PATH, you need to use a slightly different command to activate your environment:
```
source activate fslmaths-env
```
or:
```
source activate ~/fslmaths-env
```

Once you have activated your environment, you will be able to call the commands that are installed in that environment - if you have been following the above example, you will now be able to run the fslmaths command. However, in the same way that your shell needs to be configured to use a normal FSL installation, you also need to configure your shell to treat this environment as if it is a FSL installation. You can accomplish this like so:

export FSLDIR=$CONDA_PREFIX
source $FSLDIR/etc/fslconf/fsl.sh

Tip

Activating a conda environment is not strictly necessary in order to use the commands that are installed into the environment - for many commands it is possible to simply call the command directly, e.g. <environment-location>/bin/<command>. Many FSL commands do however expect that $FSLDIR is set, and $FSLDIR/etc/fslconf/fsl.sh has been sourced.

Conda channels

All packages that can be installed with conda are hosted on channels. A conda channel is simply a web site containing an index of all available packages, and links to download them. All FSL packages and their dependencies can be downloaded from two conda channels:

The FSL conda channel is where all FSL software and datasets are hosted
The conda forge channel contains some auxillary software and also a range of third party packages on top of which FSL is built, such as boost-cpp, OpenBLAS and nibabel.

Channel order is very important, to ensure that packages are downloaded from the correct channel. When using conda to install FSL packages, you must specify both the FSL conda channel, and the conda-forge channel, in this order, i.e.:

https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/
conda-forge

or when calling conda at the command-line:

conda <command>                                               \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/ \
  -c conda-forge                                              \
   <other-options>

The FSL development channel

Occasionally the FSL developers will publish unstable versions of FSL software to the FSL development channel, which is located at https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/development/. If you are a collaborator, or want to try out the latest features of a FSL project, you can install packages from the development channel by specifying it before the public channel, e.g.:

conda <command>                                                    \
  --override-channels                                              \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/development/ \
  -c https://fsl.fmrib.ox.ac.uk/fsldownloads/fslconda/public/      \
  -c conda-forge                                                   \
   <other-options>

Install FSL with conda

Installing conda

Conda environments

Conda channels

The FSL development channel

Installing `conda`