Windows¶

On Windows, run FastSurfer in our Docker image, with Docker Desktop on WSL2. The image contains 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.

Make sure that these are installed and running:

Then choose the image for your hardware. Run the commands in Windows PowerShell.

Note

This documents the development version 2.6.0. Official Docker images only exist for releases, so the commands below use the latest release, 2.5.4, for its default CUDA version, 12.8. Images of 2.5.4 for other CUDA versions, ROCm and CPU are available on Docker Hub. To run the development version, build your own image.

NVIDIA GPU

The GPU image also needs:

Windows 11 or Windows 10 21H2 or newer,
the latest WSL kernel, or at least 4.19.121 (5.10.16.3 or newer for better performance and fixes),
an NVIDIA GPU and the latest NVIDIA CUDA driver,
the CUDA toolkit in WSL, see CUDA Support for WSL 2.

Enable NVIDIA CUDA on WSL explains how to install them. The default image runs on Turing (RTX 20) and newer GPUs with driver 580 or newer; for older GPUs or drivers, use the cu126 image instead, see NVIDIA GPUs. Then download the image:

docker pull deepmi/fastsurfer:cu128-v2.5.4

and run FastSurfer as in Example 2, for example:

docker run --gpus all --rm --user 1000:1000 \
    -v C:/Users/user/my_mri_data:/home/user/my_mri_data \
    -v C:/Users/user/my_fastsurfer_analysis:/home/user/my_fastsurfer_analysis \
    -v C:/path/to/your/freesurfer/license_file:/home/user/freesurfer_license \
    deepmi/fastsurfer:cu128-v2.5.4 \
    --fs_license /home/user/freesurfer_license \
    --t1 /home/user/my_mri_data/subjectX/t1_weighted.nii.gz \
    --sid subjectX --sd /home/user/my_fastsurfer_analysis

CPU only

Download the CPU image:

docker pull deepmi/fastsurfer:cpu-v2.5.4

and run FastSurfer as in Example 2, for example:

docker run --rm --user 1000:1000 \
    -v C:/Users/user/my_mri_data:/home/user/my_mri_data \
    -v C:/Users/user/my_fastsurfer_analysis:/home/user/my_fastsurfer_analysis \
    -v C:/path/to/your/freesurfer/license_file:/home/user/freesurfer_license \
    deepmi/fastsurfer:cpu-v2.5.4 \
    --fs_license /home/user/freesurfer_license \
    --t1 /home/user/my_mri_data/subjectX/t1_weighted.nii.gz \
    --device cpu \
    --sid subjectX --sd /home/user/my_fastsurfer_analysis

Windows paths cannot be mounted at the same path inside the container, so the examples map C:/Users/user/<dir_name> to /home/user/<dir_name> and pass the container paths to FastSurfer, the FreeSurfer license file included.

FastSurfer refuses to run as root or as the image’s default user, so the examples pass a user with --user. On Linux that is your own user ($(id -u):$(id -g)), but PowerShell has no id command, and Windows folders do not have Linux user IDs anyway, so pass a fixed user ID instead, for example 1000:1000.

Docker Desktop reserves only part of your memory for WSL2. FastSurfer needs at least the memory in the system requirements; if it fails, check how much memory your WSL2 distribution has.