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.

Set up

FastSurfer runs in Docker, inside WSL2, the Linux environment of Windows:

  1. Install WSL2: open PowerShell as administrator, run wsl --install, and restart Windows. This also installs Ubuntu.

  2. Install Docker Desktop, start it, and switch on the WSL integration for Ubuntu under Settings > Resources > WSL integration.

  3. For an NVIDIA GPU, install the latest NVIDIA driver for WSL in Windows.

  4. Open Ubuntu from the Start menu. Run the FastSurfer commands in this terminal, not in PowerShell. Check Docker there, for example:

    docker run --rm hello-world

WSL2 gets only part of the computer’s memory; the system requirements say how much FastSurfer needs, and the launcher warns if Docker has less.

For a GPU, the requirements in the NVIDIA GPU tab below apply as well.

Then the launcher writes the Docker command for you. In the Ubuntu terminal, for example:

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

It picks the image for your NVIDIA GPU (or the CPU image), downloads it, shares the folders with the container and runs it as your WSL user. Keep the data in your WSL home folder: Windows folders are available below /mnt/c/, but reading them from WSL is slower.

Without the launcher

Choose the image for your hardware and run the commands in Windows PowerShell.

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:cu132-v2.6.0

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:cu132-v2.6.0 \
    --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

Download the CPU image:

docker pull deepmi/fastsurfer:cpu-v2.6.0

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.6.0 \
    --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. The launcher warns if Docker has less, and the limit is set in %UserProfile%\.wslconfig.