Welcome to FastSurfer!

Overview

FastSurfer is a fast and accurate deep-learning based neuroimaging pipeline. It provides a fully compatible FreeSurfer alternative for volumetric analysis (within minutes) and surface-based thickness analysis (in about half an hour), and it supports sub-millimeter resolutions down to 0.7mm (see the modules below for details).

The FastSurfer pipeline consists of two main parts for segmentation and surface reconstruction.

• the segmentation sub-pipeline (seg) employs advanced deep learning networks for fast, accurate segmentation and volumetric calculation of the whole brain and selected substructures.
• the surface sub-pipeline (recon-surf) reconstructs cortical surfaces, maps cortical labels and performs a traditional point-wise and ROI thickness analysis.

Segmentation Modules

• a few minutes on a GPU, --seg_only only runs this part.

Modules (all run by default):

1. asegdkt: FastSurferVINN for whole brain segmentation (deactivate with --no_asegdkt)
   • the core, outputs anatomical segmentation and cortical parcellation and statistics of 95 classes, mimics FreeSurfer’s DKTatlas.
   • requires a T1w image (notes on input images), supports high-res (up to 0.7mm, experimental beyond that).
   • performs bias-field correction and calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
2. cc: CorpusCallosum for corpus callosum segmentation and shape analysis (deactivate with --no_cc)
   • requires asegdkt_segfile (segmentation) and orig.mgz from the segmentation stage. In the standard pipeline this image is in FastSurfer conform space; with --seg_only --keepgeom it stays in native geometry, with only intensity scaling and dtype conversion as needed. Outputs include CC segmentation, thickness, and shape metrics.
   • standardizes brain orientation based on AC/PC landmarks (orient_volume.lta).
3. cereb: CerebNet for cerebellum sub-segmentation (deactivate with --no_cereb)
   • requires asegdkt_segfile, outputs cerebellar sub-segmentation with detailed WM/GM delineation.
   • requires a T1w image (notes on input images), which will be resampled to 1mm isotropic images (no native high-res support).
   • calculates volume statistics corrected for partial volume effects (skipped if --no_biasfield is passed).
4. hypothal: HypVINN for hypothalamus subsegmentation (deactivate with --no_hypothal)
   • outputs a hypothalamic subsegmentation including 3rd ventricle, c. mammilare, fornix and optic tracts.
   • a T1w image is highly recommended (notes on input images), supports high-res (up to 0.7mm, but experimental beyond that).
   • allows the additional passing of a T2w image with --t2 <t2_path>, which will be registered to the T1w image (see --reg_mode option).
   • calculates summary statistics based on the biasfield-corrected T1w image (skipped if --no_biasfield is passed).

Surface reconstruction

• approximately 20 to 40 minutes with both hemispheres in parallel (the default), --surf_only runs only the surface part.
• supports high-resolution images (up to 0.7mm, experimental beyond that).
• requires a FreeSurfer license file as it uses some FreeSurfer binaries internally.
• requires outputs of the asegdkt and the cc modules as a prerequisite (can be included in the same run).

Extensions

• FastSurfer-LIT wraps the FastSurfer segmentation and surface pipelines with lesion inpainting when a lesion mask is provided via --lesion_mask <lesion_mask_path>. Review LIT-modified outputs before using them for downstream analyses.

Requirements to input images

All pipeline parts and modules require good quality MRI images, preferably from a 3T MR scanner. FastSurfer expects a similar image quality as FreeSurfer, so what works with FreeSurfer should also work with FastSurfer. Notwithstanding module-specific limitations, resolution should be between 1mm and 0.7mm isotropic (slice thickness should not exceed 1.5mm). Preferred sequence is Siemens MPRAGE or multi-echo MPRAGE. GE SPGR should also work. See --vox_size flag for high-res behaviour.

Getting started

Installation

Choose the installation for your system (the links lead to the instructions):

• macOS with Apple silicon: the installer package, with all software included.
• macOS with an Intel CPU: Docker.
• Linux: our Apptainer/Singularity or Docker images, for NVIDIA GPUs, AMD GPUs (experimental) or CPU only.
• Windows: Docker in WSL2.
• Developers: the installation from source gives full control (documented for Ubuntu).

The images we provide on Docker Hub and the macOS package include all software FastSurfer needs. The surface pipeline also needs a FreeSurfer license file, which is free but not included. The installation overview helps to choose and explains the license.

Usage

All installation methods use the run_fastsurfer.sh call interface (replace the placeholder <fastsurfer_flags> with FastSurfer flags), which is the general starting point for FastSurfer. However, there are different ways to call this script depending on the installation, which we explain here:

1. For container installations, you need to set up the container (<singularity_flags> or <docker_flags>) in addition to the <fastsurfer_flags>:

   1. For Singularity, the syntax is

      singularity run <singularity_flags> \
                      <sif_path> \
                      <fastsurfer_flags>
      

      This command has two placeholders for flags: <singularity_flags> and <fastsurfer_flags>. <singularity_flags> set up the Apptainer environment, <fastsurfer_flags> include the options that determine the behavior of FastSurfer:

      Basic FastSurfer Flags

      • --t1: the path to the image to process.
      • --sd: the path to the "Subjects Directory", where all results will be stored.
      • --sid: the identified for the results for this image (folder inside "Subjects Directory").
      • --fs_license: path to the FreeSurfer license file.

      All options are explained in detail in the run_fastsurfer.sh documentation.

      An example for a simple full FastSurfer-Singularity command is

      freesurfer_license=${freesurfer_license:-/path/to/your/freesurfer/license_file}
      singularity run --nv \
                      -B $HOME/my_mri_data \
                      -B $HOME/my_fastsurfer_analysis \
                      -B $freesurfer_license \
                      $HOME/my_singularity_images/fastsurfer-{{ CUDA_STRING }}-v{{ FASTSURFER_VERSION }}.sif \
                      --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz \
                      --sd $HOME/my_fastsurfer_analysis \
                      --sid subjectX \
                      --fs_license $freesurfer_license

      See also Example 1 for a full singularity FastSurfer run command and Running FastSurfer in a container for details on more Apptainer flags, and Linux for how to create the <sif_path>.

   2. For docker, the syntax is

      docker run <docker_flags> \
                 deepmi/fastsurfer:<device>-v<version> \
                 <fastsurfer_flags>
      

      The options for <docker_flags> and <fastsurfer_flags> follow very similar patterns as for Singularity (but the names of <docker_flags> are different).

      Example 2 also details a full FastSurfer run inside a Docker container and Running FastSurfer in a container for more details on <docker_flags>, and Linux for the naming of Docker images (<device>-v<version>).

2. For a macOS package install, start FastSurfer from Applications and call the run_fastsurfer.sh FastSurfer script with FastSurfer flags from the terminal that is opened for you.

3. For a native install, call the run_fastsurfer.sh FastSurfer script directly. Your FastSurfer python environment needs to be set up and activated.

   # activate fastsurfer environment
   source <fastsurfer_home>/.venv/bin/activate
   
   run_fastsurfer.sh <fastsurfer_flags>
   

   Example 3 also illustrates the running the FastSurfer pipeline natively.

If your input data is organized as a BIDS dataset, the bids_fastsurfer.py BIDS-App entrypoint discovers subjects and sessions for you:

export FASTSURFER_HOME=${FASTSURFER_HOME:-/path/to/FastSurfer}
freesurfer_license=${freesurfer_license:-/path/to/your/freesurfer/license_file}
$FASTSURFER_HOME/bids_fastsurfer.py \
    $HOME/my_bids_dataset $HOME/my_fastsurfer_analysis participant \
    --participant_label 01 02 --fs_license $freesurfer_license

See the BIDS documentation for details.

Examples

The documentation includes detailed Examples on how to use FastSurfer.

• Example 1: FastSurfer Singularity
• Example 2: FastSurfer Docker
• Example 3: Native FastSurfer on subjectX with parallel processing of hemis
• Example 4: FastSurfer on multiple subjects
• Example 5: Quick Segmentation
• Example 6: Running FastSurfer on a SLURM cluster via Singularity
• Example 7: Running FastSurfer with lesion inpainting using neurolit

Output files

Modules output can be found here: FastSurfer_Output_Files

• Segmentation module
• Corpus Callosum module
• Cerebnet module
• HypVINN module
• Surface module

System Requirements

Recommendation

• Intel or AMD CPU (6 or more cores)
• 16 GB system memory
• NVIDIA graphics card (2016 or newer; see which image fits your GPU)
• 12 GB graphics memory

On a Mac, we recommend Apple silicon (M1 or newer) with 16 GB memory; FastSurfer uses its GPU automatically.

FastSurfer supports multiple hardware acceleration modes: fully CPU (--device cpu), partial GPU (--device cuda --viewagg_device cpu) and fully GPU (--device cuda). By default, FastSurfer will try to pick the best option. These modes require different system and video memory capacities, see the table below.

Voxel size	mode: fully CPU	mode: partial gpu	mode: fully GPU
1mm	system memory (RAM): 8 GB	RAM: 8 GB, graphics memory (VRAM): 2 GB	RAM: 8 GB, VRAM: 6 GB
0.8mm	RAM: 8 GB	RAM: 8 GB, VRAM: 2 GB	RAM: 8 GB, VRAM: 8 GB
0.7mm	RAM: 16 GB	RAM: 16 GB, VRAM: 3 GB	RAM: 8 GB, VRAM: 8 GB

The default device is the GPU. The view-aggregation device can be switched to CPU and requires less GPU memory. CPU-only processing --device cpu is much slower and not recommended.

Expert usage

Individual modules and the surface pipeline can be run independently of the full pipeline script documented in this documentation. This is documented in READMEs in subfolders, for example: whole brain segmentation only with FastSurferVINN, cerebellum sub-segmentation, hypothalamic sub-segmentation, corpus callosum analysis and surface pipeline only (recon-surf).

Specifically, the segmentation modules feature options for optimized parallelization of batch processing.

FreeSurfer Downstream Modules

FreeSurfer provides several Add-on modules for downstream processing, such as subfield segmentation ( hippocampus/amygdala, brainstem, thalamus and hypothalamus ) as well as TRACULA. FastSurfer creates the files these modules need under different names (e.g. using "mapped" or "DKT" to make clear that these files are from our segmentation using the DKT Atlas protocol, and mapped to the surface), and provides symlinks with the names the modules expect. Most subfield segmentations require wmparc.mgz and work very well with FastSurfer, so feel free to run those pipelines after FastSurfer. TRACULA requires aparc+aseg.mgz, which is linked as well, but we have not tested if it works, given that DKT-atlas merged a few labels. You should source FreeSurfer {{ FREESURFER_VERSION }} to run these modules.

Want to know more?

The DeepMI lab hosts an annual FastSurfer course at the German Center for Neurodegenerative Diseases in Bonn, Germany. This is a 2.5-day, hands-on, introductory course on state-of-the-art deep-learning methods for fast and reliable neuroimage analysis. Participants will gain an understanding of modern methods for the analysis of structural brain images, learn how to run both the FastSurfer and FreeSurfer packages, and will know how to set up an analysis and work with the resulting outputs in the context of their own research projects. The course consists of lectures, demonstrations, practical exercises, and provides ample opportunities for discussions and informal exchange. The course typically takes place in September. Check out our website for details and current information!

Intended Use

This software can be used to compute statistics from an MR image for research purposes. Estimates can be used to aggregate population data, compare groups etc. The data should not be used for clinical decision support in individual cases and, therefore, does not benefit the individual patient. Be aware that for a single image, produced results may be unreliable (e.g. due to head motion, imaging artefacts, processing errors etc). We always recommend to perform visual quality checks on your data, as also your MR-sequence may differ from the ones that we tested. No contributor shall be liable to any damages, see also our software LICENSE.

References

If you use this for research publications, please cite:

• Henschel L, Conjeti S, Estrada S, Diers K, Fischl B, Reuter M. FastSurfer - A fast and accurate deep learning based neuroimaging pipeline. NeuroImage 219 (2020), 117012. doi:10.1016/j.neuroimage.2020.117012
• Henschel L*, Kuegler D*, Reuter M. (*co-first) FastSurferVINN: Building Resolution-Independence into Deep Learning Segmentation Methods - A Solution for HighRes Brain MRI. NeuroImage 251 (2022), 118933. doi:10.1016/j.neuroimage.2022.118933
• Faber J*, Kuegler D*, Bahrami E*, et al. (*co-first) CerebNet: A fast and reliable deep-learning pipeline for detailed cerebellum sub-segmentation. NeuroImage 264 (2022), 119703. doi:10.1016/j.neuroimage.2022.119703
• Estrada S, Kuegler D, Bahrami E, Xu P, Mousa D, Breteler MMB, Aziz NA, Reuter M. FastSurfer-HypVINN: Automated sub-segmentation of the hypothalamus and adjacent structures on high-resolutional brain MRI. Imaging Neuroscience 1 (2023), 1–32. doi:10.1162/imag_a_00034
• Pollak C, Diers K, Estrada S, Kuegler D, Reuter M. FastSurfer-CC: A robust, accurate, and comprehensive framework for corpus callosum morphometry. Imaging Neuroscience (2026). doi:10.1162/IMAG.a.1221

If you use the lesion inpainting extension, please also cite:

• Pollak C, Kuegler D, Bauer T, Rueber T, Reuter M. FastSurfer-LIT: Lesion Inpainting Tool for Whole Brain MRI Segmentation with Tumors, Cavities and Abnormalities. Imaging Neuroscience (2025). doi:10.1162/imag_a_00446

Stay tuned for updates and follow us on X/Twitter.

Acknowledgements

This project is partially funded by:

• Chan Zuckerberg Initiative
• German Federal Ministry of Education and Research
• Helmholtz Software Award

The recon-surf pipeline is largely based on FreeSurfer.