MacOS Install & Setup

The examples below show how to unpack/install the Freesurfer 7.0.0 beta 1 MacOS tar archive, freesurfer-darwin-macOS_HighSierra-7.0.0-beta.tar.gz, or pkg file, freesurfer-MacOS-7.0.0b1-x86_64.pkg. While the code was built and packaged on Mac OS 10.13 (High Sierra), you should follow the same instructions if you are running MacOS 10.12 (Sierra), 10.14 (Mojave) or 10.15 (Catalina).

On Mac systems, the tar archive file (.tar.gz) can be expanded under any convenient path/subdirectory on your machine you have permission to write to. For example, you can expand the tar archive under your $HOME directory. To install freesurfer under a recommended shared system location, e.g., /Applications, you may need sudo or root privileges. Please note that if you have sudo/root privileges, then you should consider using the package file (.pkg) to install the freesurfer 7.0.0 beta 1 release.

Example of placing the Mac tar archive under the $HOME directory belonging to user "tester" without using sudo/root privileges. Setup commands follow. Shell is bash or Bourne shell.

$ cd $HOME
$ pwd
/home/tester
$ tar -zxvpf freesurfer-darwin-macOS_HighSierra-7.0.0-beta.tar.gz
x freesurfer/
x freesurfer/ASegStatsLUT.txt
x freesurfer/average/
x freesurfer/bin/
x freesurfer/build-stamp.txt
x freesurfer/DefectLUT.txt
...
..
<rest of output deleted>

$ cd freesurfer
$ pwd
/home/tester/freesurfer
$ export FREESURFER_HOME=$HOME/freesurfer
$ export SUBJECTS_DIR=$FREESURFER_HOME/subjects
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-darwin-macOS_HighSierra-7.0.0-beta-xxxxxx --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /home/tester/freesurfer
FSFAST_HOME       /home/tester/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /home/tester/freesurfer/subjects
MNI_DIR           /home/tester/freesurfer/mni

$ which freeview
/home/tester/freesurfer/bin/freeview

Example of placing the Mac tar archive under the system location /Applications by user "tester" using sudo/root privileges. Setup commands follow. Shell is bash or Bourne shell.

$ cd $HOME
$ pwd
/home/tester
$ sudo tar -C /Applications -zxvpf freesurfer-darwin-macOS_HighSierra-7.0.0-beta.tar.gz
x freesurfer/
x freesurfer/ASegStatsLUT.txt
x freesurfer/average/
x freesurfer/bin/
x freesurfer/build-stamp.txt
x freesurfer/DefectLUT.txt
...
..
<rest of output deleted>

$ export FREESURFER_HOME=/Applications/freesurfer
$ export SUBJECTS_DIR=$FREESURFER_HOME/subjects
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-darwin-macOS_HighSierra-7.0.0-beta-xxxxxx --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /Applications/freesurfer
FSFAST_HOME       /Applications/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /Applications/freesurfer/subjects
MNI_DIR           /home/tester/freesurfer/mni

$ which freeview
/Applications/freeview/bin/freeview

Using the Mac Package Installer

Please note - if you already have freesurfer installed as /Applications/freesurfer, e.g., per the example above, then it is strongly advised that you remove the installation or rename the directory to be something other than freesurfer under /Applications. This is because the Mac pkg installer will install freesurfer under the path /Applications/freesurfer/<package version>.

The package installer will also save package receipts on the system and provides an uninstaller script as /Applications/freesurfer/<package version>/uninstall.sh

Performing the install

We hope to offer a signed installer package in the future, but in the meantime security exceptions need to be made in order to run the downloaded freesurfer package installer. Older versions of MacOS may not display all the security opt-out dialogue messages pictured below (run on MacOS 10.15, Catalina). Please note that while some Mac users disable SIP (system integrity protection) to simplify unsigned installs, as of this writing it should not be necessary to disable SIP to install files under /Applications.

Verify and Enable the Installer

The screen shots below show the steps to allow the freesurfer unsigned installer to run. This includes opening the System Preferences panel found under the Apple logo pull down menu in the uppermost left hand corner of the Mac display. Once in the System Preferences panel, click on the Network and Security icon to bring up the panel that will allow you to click on OK to run the installer. If your Mac user account has sudo privileges (the default for the account created on a brand new machine taken out of the box), then you should not need to use an administrators password to unlock the padlock in the Network and Security panel.

Double click on the installer icon to start the install process.

MacOS_install_info.png

... the installer will start to verify, and not find a signature...

MacOS_verify_1.png

... allow the security exception ...

MacOS_verify_2.png

... from the Apple logo pull down menu (upper left hand screen corner) select System Preferences ...

... click on Security & Privacy icon ...

MacOS_verify_3.png

... allow the security exception ...

MacOS_verify_4.png

... with the override, the installer should finish verifying ...

MacOS_verify_5.png

... allow the security exception ...

MacOS_verify_6.png

Allow Installer to Write Files

You should now see the first or "Introduction" splash screen of the installer. The screen shots below show the steps for running the package installer; these include agreeing to the license, selecting the install destination, and allowing the installer to transfer files.

MacOS_install_1_8.png

MacOS_install_2_8.png

MacOS_install_3_8.png

MacOS_install_4_8.png

... enter userid and password for a user with admin privileges ...

MacOS_install_EnterPasswd.png

MacOS_install_5_8.png

MacOS_install_6_8.png

MacOS_install_8_8.png

After the installer program exits, use a terminal window to setyp the environment following using the same commands listed above except that the path for FREESURFER_HOME is now /Applications/freesurfer/7.0.0b1.

$ export FREESURFER_HOME=/Applications/freesurfer/7.0.0b1
$ export SUBJECTS_DIR=$FREESURFER_HOME/subjects
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-darwin-macOS_HighSierra-7.0.0-beta-xxxxxx --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
WARNING: /Users/synpro/freesurfer/fsfast does not exist
FREESURFER_HOME   /Applications/freesurfer/7.0.0b1
FSFAST_HOME       /Users/synpro/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /Applications/freesurfer/7.0.0b1/subjects
MNI_DIR           /Users/synpro/freesurfer/mni

$ which freeview
/Applications/freesurfer/7.0.0b1/bin/freeview

Screenshot of loading a volume in freeview (using the same environment settings).

MacOS_run_freeview.png