Linux¶

On Linux, run FastSurfer in one of our container images: they contain the full pipeline (segmentation and surface reconstruction) and all software it needs. The surface reconstruction also needs a FreeSurfer license, which is free but not included: get it from FreeSurfer before your first full run. We provide images for NVIDIA GPUs (CUDA), for AMD GPUs (ROCm, experimental) and for the CPU only, on Docker Hub.

A GPU with enough memory makes the segmentation much faster, see the system requirements. Without a GPU, use the CPU image.

Set up¶

FastSurfer runs in a container, with Apptainer (or its predecessor Singularity) or Docker. Check whether one of them works, for example:

# Apptainer (with Singularity: singularity --version)
apptainer --version
# Docker
docker run --rm hello-world

Clusters usually provide Apptainer, often as a module (module load apptainer, see your cluster’s documentation). Installing Apptainer or Docker needs administrator rights, so if neither works, ask your administrator to install Apptainer or Docker. Docker also needs:

your user in the docker group, to run containers without sudo (log out and back in once you were added),
for NVIDIA GPUs, the NVIDIA Container Toolkit. Apptainer needs only the NVIDIA driver.

Then the launcher does the rest: it picks the image for your NVIDIA GPU and driver (or for an AMD GPU, experimental, or the CPU image), downloads it, and runs FastSurfer with the flags of run_fastsurfer.sh:

curl -fsSLO https://deep-mi.org/FastSurfer/dev/fastsurfer
chmod +x fastsurfer
./fastsurfer --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz \
    --sid subjectX --sd $HOME/my_fastsurfer_analysis

The sections below explain the images and how to download them by hand.

The images are tagged deepmi/fastsurfer:<device>-v<version>, where <device> is cu<cuda_version> for NVIDIA GPUs (see below), rocm<rocm_version> for AMD GPUs (experimental), or cpu without GPU support (smaller and thus faster to download), and <version> is the FastSurfer version. latest points to the newest NVIDIA image, with the default CUDA version of that release, and cpu-latest to the newest CPU image. Docker Hub lists all tags. For reproducible results, use a versioned tag.

NVIDIA GPUs¶

We build the images for two CUDA versions, because newer CUDA versions drop old GPUs and older ones lack the newest:

Image	CUDA	GPUs	NVIDIA driver
`cu132-v<version>` (default)	13.2	Turing (RTX 20, T4) to Blackwell (RTX 50, B200)	580 or newer
`cu126-v<version>`	12.6	Maxwell (GTX 900) to Hopper (H100), including Pascal (GTX 10, P100) and Volta (V100), but not Blackwell	525 or newer

Use the default image unless your GPU is older than Turing or your driver is older than 580; then use the 12.6 image. nvidia-smi shows the name of your GPU and the driver version.

If FastSurfer cannot use your GPU, because the image has no support for it, the driver is too old, or the container was started without access to the GPU, it says so, names the image or flag to use instead, and runs on the CPU, which takes much longer.

Apptainer or Singularity¶

Apptainer is the open-source continuation of Singularity, and both run the same images. Apptainer also installs the singularity command, so the commands below work with either; with Apptainer, you can also write apptainer instead of singularity.

With Apptainer (or Singularity) installed, build an image from our Docker image, for example in $HOME/my_singularity_images:

mkdir -p $HOME/my_singularity_images
singularity build \
    $HOME/my_singularity_images/fastsurfer-cu132-v2.6.0.sif \
    docker://deepmi/fastsurfer:cu132-v2.6.0

Running FastSurfer in a container shows how to run FastSurfer with it and explains the flags.

Docker¶

With Docker installed, download our image:

docker pull deepmi/fastsurfer:cu132-v2.6.0

Running FastSurfer in a container shows how to run FastSurfer with it and explains the flags.

For NVIDIA GPUs, Docker needs the NVIDIA Container Toolkit. In Docker’s rootless mode, also follow its configuration for the rootless mode, otherwise Docker stops with docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]].

CPU only¶

Without a GPU, use the CPU image, which is smaller. It runs the same pipeline, only the segmentation takes longer. For Apptainer (or Singularity):

mkdir -p $HOME/my_singularity_images
singularity build \
    $HOME/my_singularity_images/fastsurfer-cpu-v2.6.0.sif \
    docker://deepmi/fastsurfer:cpu-v2.6.0

or, for Docker:

docker pull deepmi/fastsurfer:cpu-v2.6.0

Run it as described in Running FastSurfer in a container, without --nv (Apptainer or Singularity) or --gpus all (Docker).

AMD GPUs (experimental)¶

We have successfully run the segmentation on an AMD GPU (Radeon Pro W6600) with ROCm. This needs a supported (or semi-supported) GPU and the right kernel version. Install the AMD kernel modules on the host as described in the ROCm installation instructions, and add your user to the groups they name.

The launcher uses the ROCm image when the machine has an AMD GPU and no NVIDIA GPU, or when you pass --image rocm. It runs with Docker or Apptainer and adds the flags below. Its image supports several AMD architectures; for another GPU of the same family, such as the W6600 (gfx1032, family gfx1030), it sets HSA_OVERRIDE_GFX_VERSION and says so.

Without the launcher, download our image for ROCm 7.2:

docker pull deepmi/fastsurfer:rocm7.2-v2.6.0

AMD needs a few more flags in the docker run command, see Running FastSurfer in a container for <docker_flags> and <fastsurfer_flags>. To build your own ROCm image, see Building FastSurfer Docker images.

Usage:

docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
        --device=/dev/kfd --device=/dev/dri --group-add video \
        --ipc=host --shm-size 8G \
        <docker_flags> deepmi/fastsurfer:rocm7.2-v2.6.0 \
                <fastsurfer_flags>

This image is experimental and uses different Python packages, so its results can differ from our validation results. Check them visually.

Installing from source¶

To install FastSurfer without containers, see installing from source.