macOS

On a Mac with Apple silicon (M1 or newer), install the FastSurfer package: it contains all software FastSurfer needs, and it uses the Apple GPU automatically. The surface reconstruction also needs a FreeSurfer license, which is free but not included. On a Mac with an Intel CPU, use Docker instead.

FastSurfer for macOS

Apple silicon (M1 or newer) · macOS 14 (Sonoma) or newer · about 1 GB download

Includes its own Python, all Python packages, the network checkpoints and the FreeSurfer tools FastSurfer uses: no other software to install, and no internet connection needed after the download.

Download the installer (.pkg)

Other versions · Intel Mac? Use Docker

Install

1. Download the installer with the button above. It always points to the newest release.

2. Double-click the downloaded .pkg file and follow the installer. You need about 2.5 GB of free disk space.

3. The installer places two items in your Applications folder: FastSurfer<version>, the installation, and FastSurfer<version>.app, a small app that opens a Terminal window set up to run FastSurfer.

macOS blocks the installer (“cannot be opened”)

The installer is not signed by Apple yet, so macOS Gatekeeper blocks it. Depending on your macOS version, the warning may not offer an “Open” button at all, only “Done” or “Move to Trash”. To allow it:

1. Click Done on the warning.

2. Open System Settings > Privacy & Security and scroll down to the Security section.

3. Click Open Anyway next to the message about the blocked installer, and confirm once more (with your password or Touch ID).

4. The installer usually starts by itself now; if it does not, double-click the .pkg file again.

Run FastSurfer

Open the FastSurfer app from your Applications folder (or with Spotlight). It opens a Terminal window, the FastSurfer console, in which the environment is set up to run FastSurfer; you recognize it by the (FastSurfer<version>) prompt. The first time, macOS asks whether FastSurfer may control Terminal; allow it, because that is how the app opens the console. If you declined, switch on Terminal below FastSurfer in System Settings > Privacy & Security > Automation.

In the console, call run_fastsurfer.sh with the FastSurfer flags. For example, the segmentation only:

run_fastsurfer.sh --seg_only --sd $HOME/my_fastsurfer_analysis --sid subjectX \
    --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz

For the full pipeline with surfaces, pass your FreeSurfer license, for example:

freesurfer_license=${freesurfer_license:-/path/to/your/freesurfer/license_file}
run_fastsurfer.sh --sd $HOME/my_fastsurfer_analysis --sid subjectX \
    --t1 $HOME/my_mri_data/subjectX/t1_weighted.nii.gz \
    --fs_license $freesurfer_license

FastSurfer uses the Apple GPU (mps) automatically, so no --device flag is needed.

FreeSurfer license

On macOS, FastSurfer cannot find the FreeSurfer license inside the bundled FreeSurfer ($FREESURFER_HOME), because the installer places that folder as root and you cannot copy files into it. Save the license file in your home folder instead, and either pass it with --fs_license as above or set it for the current console:

export FS_LICENSE=/path/to/your/freesurfer/license_file

To set it in every console, including the one the FastSurfer app opens, add that line to your shell profile yourself (~/.zprofile for zsh, the macOS default, or ~/.bash_profile for bash). FastSurfer does not change these files.

More details

What the FastSurfer console sets up

The console is a bash session that:

• puts the Python bundled with FastSurfer ($FASTSURFER_HOME/python) first on PATH,

• sets FASTSURFER_HOME and PYTHONPATH,

• sets FREESURFER_HOME to the FreeSurfer tools bundled with FastSurfer and sources SetUpFreeSurfer.sh,

• adds the FastSurfer folder (and GNU grep, if you have it from Homebrew) to PATH, for this session only,

• reads your ~/.bashrc first, if you have one, so your own aliases and settings are still there, and

• reminds you to set FS_LICENSE if it is not set yet.

No shell profile is modified.

Using FastSurfer without the app

In a bash or zsh Terminal window, you can set up the same environment by sourcing the script the app uses:

source /Applications/FastSurfer2.5.4/macos_setup_fastsurfer.sh

The script is bash syntax, so from tcsh or fish, start bash (or zsh) first and source it there.

Only adding the FastSurfer folder to your PATH is not enough: run_fastsurfer.sh would be found, but python3 would be Apple’s system Python, which is too old for FastSurfer, and FREESURFER_HOME would not be set.

Requirements in detail

• Apple silicon only: PyTorch publishes no macOS packages for Intel CPUs, so the Python environment the package bundles cannot be built for them. On an Intel Mac, use Docker.

• macOS 14 (Sonoma) or newer: the bundled programs are built for it and do not start on older versions. We do not test specific macOS versions, so this is a lower bound rather than a support statement.

• Shells: only the shells macOS ships, /bin/bash for FastSurfer’s scripts and /bin/tcsh for FreeSurfer’s. Your own Terminal shell does not matter, because the app starts a bash session itself.

• No Python and no Homebrew are needed.

Uninstalling

Drag both items from your Applications folder to the Trash:

• FastSurfer<version> (the installation)

• FastSurfer<version>.app (the app that opens the console)

macOS asks for your password, because the installer placed them as root. Everything FastSurfer installed is in these two items: no shell profile is modified and nothing is written elsewhere. Installations of other versions are independent and stay as they are.

To also remove the installer’s receipt (bookkeeping only, it does not affect anything you run):

sudo pkgutil --forget org.deep-mi.FastSurfer.<version_without_dots>_<arch>

pkgutil --pkgs | grep -i fastsurfer lists the exact names.

Docker (Intel Macs)

The package does not run on Intel Macs, but Docker does, with the full pipeline on the CPU (2 to 4 times slower than on Apple silicon).

1. Install Docker Desktop for Mac, start it, and under Settings > Resources set the memory to 15 GB (or the most you have; with less than that, it may fail).

2. Download the CPU image. Open a Terminal window and run:

   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. To run the development version, build your own image.

   docker pull deepmi/fastsurfer:cpu-v2.5.4
   

3. Run FastSurfer as in Example 2, with the CPU image and without --gpus all.