FreeSurfer (2025): Install, License Setup & First Recon-All Guide

FreeSurfer 8.1 (2025): Fast Setup & Your First recon-all on Mac and Ubuntu

New to FreeSurfer or upgrading in 2025?

In this guide I’ll show how to install FreeSurfer 8.x, set the license, run your first recon-all, and avoid common errors. The steps work on macOS (Intel/Apple Silicon), Ubuntu/WSL, and typical lab workstations.

---

Covering the steps

1. Download and install FreeSurfer 8.x (Mac: .pkg, Ubuntu: .deb).
2. Drop your license.txt in $HOME and set FS_LICENSE.
3. Source SetUpFreeSurfer.sh and define SUBJECTS_DIR.
4. Run recon-all -i T1.nii.gz -s Subj001 -all.
5. QC in Freeview (white/pial surfaces, skull strip, segmentations).

---

Download & Install (Mac / Ubuntu / WSL)

Download FreeSurfer 8.1: Official FreeSurfer Download Page

macOS (Intel or Apple Silicon)

1. Download the latest FreeSurfer-8.x.x-macOS.pkg.
2. Run the installer (default path is /Applications/freesurfer/8.x.x).
3. Open Terminal and source the setup script:
   

   export FREESURFER_HOME=/Applications/freesurfer/8.1.0
   source $FREESURFER_HOME/SetUpFreeSurfer.sh

Ubuntu 22.04+ (incl. WSL on Windows)

1. Install dependencies (examples):
   

   sudo apt-get update
   sudo apt-get install -y tcsh libglu1 libxss1

2. Download and install the .deb package:
   

   cd ~/Downloads
   sudo dpkg -i freesurfer_ubuntu22-8.1.0_amd64.deb  # adjust for your file name

3. Set environment and source:
   

   export FREESURFER_HOME=/usr/local/freesurfer/8.1.0
   source $FREESURFER_HOME/SetUpFreeSurfer.sh

Tip (Linux+NVIDIA):

To switch the bundled Python to GPU‑enabled Torch later, run:

sudo $FREESURFER_HOME/bin/fs_install_cuda (optional).

---

Set Your License (Required)

Register for a free key and place your license.txt in $HOME. Then set the environment variable so FreeSurfer can always find it:

# Bash (Linux/macOS)
echo 'export FS_LICENSE=$HOME/license.txt' >> ~/.bashrc
export FS_LICENSE=$HOME/license.txt

# tcsh/csh
echo 'setenv FS_LICENSE $HOME/license.txt' >> ~/.cshrc

Why this matters: many tools (and containers like fMRIPrep) look for the license at --fs-license-file or via $FS_LICENSE.

---

Run Your First recon-all

# Choose a subjects directory to hold outputs
export SUBJECTS_DIR=$HOME/freesurfer-subjects
mkdir -p "$SUBJECTS_DIR"

# Run full pipeline on a single T1
recon-all -i /path/to/T1w.nii.gz -s Subj001 -all

# After it finishes, inspect with Freeview
freeview -v $SUBJECTS_DIR/Subj001/mri/T1.mgz \
         -f $SUBJECTS_DIR/Subj001/surf/lh.white:edgecolor=yellow \
            $SUBJECTS_DIR/Subj001/surf/lh.pial:edgecolor=red

Runtime: on modern desktops/laptops, expect a few hours on a single multi‑core CPU. Close other heavy apps and avoid running in a VM to keep things smooth.

---

What’s New/Important in Late‑2025

• 8.1.x (July 2025): stability fixes (e.g., a symlink bug), upgrades to converters, and infant pipeline improvements.
• 8.0.x (Feb 2025): deep‑learning‑assisted steps (e.g., SynthSeg/SynthStrip) underpin faster, more robust skull‑strip and segmentation.
• Memory notes: the faster 8.x behavior trades time for RAM. A system with 32 GB+ RAM is recommended; keep other processes minimal. If you hit memory pressure, see the toggle below.

---

Speed vs. Memory: the 8.x Toggle

8.x uses a faster default configuration. If you need to reduce memory pressure (e.g., on a small workstation), you can revert to the older behavior:

# Use legacy behavior (slower, lower peak RAM)
export FS_V8_XOPTS=0
recon-all -i T1w.nii.gz -s Subj001 -all

---

Quality Control (QC) Checklist in Freeview

• Skull strip: brain mask should tightly fit; no dura/sinuses left in.
• White surface: follows WM/GM boundary; check orbitofrontal/insula/temporal tips.
• Pial surface: should not invade CSF or veins; verify around EC/temporal pole.
• Segmentations: scan aseg.stats and aparc.stats for zeros/outliers.

---

Common Errors & Quick Fixes

• “ERROR: a valid license file is required” → Set $FS_LICENSE to your $HOME/license.txt or pass --fs-license-file in containerized workflows.
• Freeview won’t start (Linux) → install missing libs (e.g., libglu1, libxss1); on WSL you may need an X server.
• Runs out of memory → close apps; avoid VMs; ensure swap; try the FS_V8_XOPTS=0 toggle above.
• MATLAB‑based tools needed? → install the supported MATLAB Runtime (MCR v97) per the installer notes.

---

Best Practices for Reproducibility

• Pin versions (record 8.x patch level) and save your env commands in a setup.sh.
• Use BIDS for inputs/derivatives and keep SUBJECTS_DIR under versioned project folders.
• Automate QC: export HTML reports, track outliers, and note any manual edits.

Educational content. Follow your IRB/ethics, data protection, and device guidelines.