Installing from source

A native installation runs FastSurfer directly on your system, without a container. It is the setup for developers and for systems where containers are not available. You install all dependencies yourself (system packages, Python packages and FreeSurfer in the supported version), so the results can differ from our testing environment, and we may not be able to help if something does not work. We test FastSurfer with Ubuntu 24.04, the base of our Docker images, and the steps below are for Ubuntu.

  1. System packages

You need a few packages that may be missing on your system (this needs sudo access, or ask a system admin):

sudo apt-get update && sudo apt-get install -y --no-install-recommends \
      wget \
      git \
      ca-certificates \
      file

You also need bash 3.2 or newer (check with bash --version). These packages are enough to install the Python dependencies and run the segmentation. The full pipeline also needs FreeSurfer (step 5).

  1. uv for Python

We recommend uv to manage the Python environment and packages. It is very fast and makes managing different environments easy. See uv’s documentation for more on installing it, for example shell autocompletion.

wget -qO- https://astral.sh/uv/install.sh | sh

Then open a new terminal (or follow the installer’s instructions), so uv is on your PATH.

  1. FastSurfer

Get FastSurfer from GitHub. Choose the stable branch (tested thoroughly) or the dev branch (newest, but it can be broken). For example, stable:

export FASTSURFER_HOME=${FASTSURFER_HOME:-/path/to/FastSurfer}
# FastSurfer will get cloned to $FASTSURFER_HOME
git clone --branch stable https://github.com/Deep-MI/FastSurfer.git \
    $FASTSURFER_HOME
cd $FASTSURFER_HOME

  1. Python environment

Create a new environment and install the FastSurfer dependencies:

# make sure you are in the FastSurfer directory!
# create a .venv environment directory inside the FastSurfer directory,
# e.g., python 3.14 (recommended)
uv venv --python python3.14
# install packages with pinned versions from the last stable release
# (recommended, that is what we tested with)
# uv pip sync only runs if uv pip compile succeeds
resolved=$(uv pip compile --no-build --torch-backend auto requirements.txt) && \
    uv pip sync --no-build --torch-backend auto - <<< "$resolved"

To select the PyTorch backend yourself, for example for testing, replace auto in both commands, e.g. with cpu or cu132:

# make sure you are in the FastSurfer directory!
resolved=$(uv pip compile --no-build --torch-backend cpu requirements.txt) && \
    uv pip sync --no-build --torch-backend cpu - <<< "$resolved"

For developers: To install the newest compatible dependency versions instead of the pinned stable ones, resolve from pyproject.toml, optionally with extras such as --extra doc or --extra all:

resolved=$(uv pip compile --torch-backend auto --extra doc pyproject.toml) && \
    uv pip sync --torch-backend auto - <<< "$resolved"

Leave out --no-build here: with the style or all extra, bibtexparser (which bibclean needs) only ships source code (pure Python, no compiler needed), and --no-build makes uv resolve different versions to avoid it. bibtexparser should be the only package uv builds (Building bibtexparser).

Activate the FastSurfer environment with:

source .venv/bin/activate

and add the FastSurfer directory to the Python path:

# make sure you are in the FastSurfer directory!
export PYTHONPATH="${PYTHONPATH}:$PWD"

You need to activate the environment and set the Python path in every new terminal before you run FastSurfer. To set the Python path automatically, add it to your ~/.bashrc if you use bash, for example:

# make sure you are in the FastSurfer directory!
echo "export PYTHONPATH=\"\${PYTHONPATH}:$(pwd)\"" >> ~/.bashrc

You can also download all network checkpoint files now (do this if you install for several users):

export FASTSURFER_HOME=${FASTSURFER_HOME:-/path/to/FastSurfer}
python3 $FASTSURFER_HOME/FastSurferCNN/download_checkpoints.py --all

With this, the segmentation runs (run_fastsurfer.sh --seg_only ...), see Example 3 for the command line flags.

  1. FreeSurfer

The full pipeline needs FreeSurfer 8.2.0 (the version we recommend and support), installed according to FreeSurfer’s instructions. The packages for each version and operating system are in the release directory. If you run into problems in this step, the FreeSurfer mailing list can help.

FastSurfer runs FreeSurfer’s Talairach registration (talairach_avi and the tools it calls), which some FreeSurfer packages leave out, among them FreeSurfer 8’s packages for Ubuntu. Use a package that includes these tools, for example the one for Rocky Linux, or run the full pipeline with our Docker or Singularity image. FastSurfer checks for talairach_avi before it starts and stops with an error if it is missing.

Set the FREESURFER_HOME environment variable, so FastSurfer finds the FreeSurfer programs, and have a FreeSurfer license.