Installing FSLeyes

There are several ways to obtain and install FSLeyes. FSLeyes comes as a standard component of an FSL installation, but can also be installed independently of FSL.

Note

The terminal commands in these instructions may require administrative privileges, depending on where you have installed FSL. If you encounter permission errors, try repeating the command, but prefixing it with sudo.

Install from PyPi (advanced)

Warning

This is an advanced option, recommended only if you are comfortable working with Python environments, and installing packages using your OS package manager. The steps below are suggestions - you will probably need to adapt them to suit your OS and environment.

FSLeyes is available on PyPi, and should work with Python 3.9 and newer. The best way to install FSLeyes from PyPi is to create an isolated virtual environment, and install FSLeyes into it.

Note

As an alternative to creating and managing your virtual environments by hand, there are many tools which can be used to manage Python environments, including pixi, uv, hatch, and poetry to name a few.

macOS users

Before installing FSLeyes, you first need to install Python. On macOS, you can do this in a number of ways, including:

Once you have installed Python, you can create and activate a virtual environment for FSLeyes with these commands:

python -m venv fsleyes-virtualenv
. ./fsleyes-virtualenv/bin/activate

Then you should be able to install FSLeyes like so:

pip install fsleyes

Linux users

Before installing FSLeyes, you first need to install Python and the wxPython runtime dependencies. Under Ubuntu 24.04, you will need to run the following command:

sudo apt install python3 python3-pip python3-venv \
  curl libegl1 libgl1 libgtk-3-0 libnotify4       \
  libpcre2-32-0 libsdl2-2.0-0 libsm6 libxxf86vm1

Then you need to create and activate a virtual environment, and install wxPython and FSLeyes into it. For example, you can use these commands to create and activate a virtual environment:

python -m venv fsleyes-virtualenv
. ./fsleyes-virtualenv/bin/activate

The easiest way to install wxPython on Linux is to use the pre-release wxPython builds available at https://extras.wxpython.org/wxPython4/extras/linux/, e.g.:

wxpyurl=https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04
pip install -f  ${wxpyurl} wxpython

Once you have installed wxPython, you can install FSLeyes:

pip install fsleyes

You should now be able to run the fsleyes command.

Install into a Docker/Singularity image

FSLeyes can be executed from Docker or Singularity containers. Here is an example Dockerfile file which contains FSLeyes:

FROM ubuntu:24.04

ENV MMURL="https://micro.mamba.pm/api/micromamba/linux-64/latest"
ENV MAMBA_ROOT_PREFIX="/micrommaba"
ENV DEBIAN_FRONTEND="noninteractive"
ENV TZ="Europe/London"

RUN apt update
RUN apt install -y curl bzip2 tar libgl1 libegl1
RUN mkdir ${MAMBA_ROOT_PREFIX}
RUN curl -Ls ${MMURL} | tar -C ${MAMBA_ROOT_PREFIX} -xvj bin/micromamba
RUN eval "$(micromamba/bin/micromamba shell hook -s posix)"
RUN micromamba install -y -p ${MAMBA_ROOT_PREFIX} -c conda-forge fsleyes

CMD [ "/micromamba/bin/fsleyes" ]

And an equivalent Singularity definition file:

Bootstrap: docker
From: ubuntu:24.04

%help
  FSLeyes Singularity image


%post
  export MMURL=https://micro.mamba.pm/api/micromamba/linux-64/latest
  export MAMBA_ROOT_PREFIX=/micromamba
  export TZ="Europe/London"
  export DEBIAN_FRONTEND="noninteractive"
  apt update
  apt install -y curl bzip2 tar libgl1 libegl1
  mkdir ${MAMBA_ROOT_PREFIX}
  curl -Ls ${MMURL} | tar -C ${MAMBA_ROOT_PREFIX} -xvj bin/micromamba
  eval "$(micromamba/bin/micromamba shell hook -s posix)"
  micromamba install -y -p ${MAMBA_ROOT_PREFIX} -c conda-forge fsleyes


%runscript
  /micromamba/bin/fsleyes "$@"