=============================
SETUP YOUR FREESURFER LICENSE
=============================
Freesurfer commands require a license in order to run. A "license.txt" file will be emailed to the address you specify when you fill out the registration form at https://surfer.nmr.mgh.harvard.edu/registration.html
While it still works to copy a license.txt file into the freesurfer tree as $FREESURFER/.license in order for the license file to be read, we highly recommend that individual users make use of the FS_LICENSE environment variable for freesurfer commands to read their individual license.txt file.
You should always have access to your home directory as setup on a machine when your account is created. Your home directory is the default destination for the "cd" command with no arguments and always denoted by the value of $HOME in whatever login shell you use.
$ cd
$ pwd
<path to your home directory>
$ cd $HOME
$ pwd
<path to your home directory>
Therefore, if you place the license.txt file in your home directory, then the path to it can always be referenced by $HOME/license.txt. If you in turn set that path as the value for FS_LICENSE in your shell initialization file, then any freesurfer distribution you set FREESURFER_HOME to point to will in turn be able to find and read your license.txt file.
In $HOME/.bashrc add
export FS_LICENSE=$HOME/license.txt
In $HOME/.cshrc add
setenv FS_LICENSE $HOME/license.txt
=======================================
NEW RECON-ALL BEHAVIOR IN 8.0.0 RELEASE
=======================================
Commands in the 8.0.0 recon-all pipeline have changed compared to previous releases and decrease the amount of time it takes to perform a recon-all on a machine with a single multi-core CPU chip, e.g., a user personal machine that is not a server or in a cluster.
Recon-all performed on subject bert from the tutorial data:
$ recon-all -all -i I50 -s Subj001
Recon-all time with new behavior:
- 1.8 hours on MacMini (darwin_arm64) with M2 chip, 32G RAM, running MacOS Sonoma (14.7.2)
- 2.5 hours on iMac (darwin_x86_64) with Intel Core i9 chip, 32G RAM, running MacOS Ventura (13.7.3)
The reduction in the amount of time it takes to run the pipeline via new python code does however require more memory compared to previous freesurfer releases. At some point during the 8.X recon-all, ~80G of RAM will be in use. A machine with efficient memory management can handle this, e.g., total system RAM = 32G with nothing but the recon-all application running directly on the host OS (and not in a virtual machine). You can revert the 8.0.0 release to the old recon-all behavior by setting the environment variable FS_V8_XOPTS=0 on the recon-all command line, e.g., for the above command,
$ export FS_V8_XOPTS=0 && recon-all -all -i I50 -s Subj001
Reverting recon-all to the old behavior increases the recon-all times on the above machines to 10+ hours. All recon-all times listed for MacOS are for the case where no other applications have been launched by the user to run on the machine.
===========================
SETUP A MATLAB DISTRIBUTION
===========================
*** IMPORTANT NOTES ***
- on Linux platforms, the LD_LIBRARY_PATH setting is incompatible with Freeview, i.e., you will not be able to run Freeview while LD_LIBRARY_PATH is set for Matlab
- we do not support a runtime environment newer than MCRv97
- we do not support users linking in their own copy of Matlab from outside the freesurfer tree
------
LINUX:
------
... setup the freesurfer environment - here using bash shell ...
$ bash
$ export FREESURFER_HOME=/usr/local/freesurfer/8.0.0
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-linux-<OS_ARCH>-8.0.0-20250203-0f2bd3a --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer/8.0.0
FSFAST_HOME /usr/local/freesurfer/8.0.0/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /usr/local/freesurfer/8.0.0/subjects
MNI_DIR /usr/local/freesurfer/8.0.0/mni
FSL_DIR /usr/pubsw/packages/fsl/current
... install either the Matlab R2014b or R2019b runtime environment ...
$ which fs_install_mcr
/usr/local/freesurfer/8.0.0/bin/fs_install_mcr
$ sudo FREESURFER_HOME=$FREESURFER_HOME $FREESURFER_HOME/bin/fs_install_mcr R2019b
<output deleted>
... set LD_LIBRARY_PATH to point to The Mathworks libraries ...
$ export LD_LIBRARY_PATH=$FREESURFER_HOME/MCRv97/runtime/glnxa64:$FREESURFER_HOME/MCRv97/bin/glnxa64:$FREESURFER_HOME/MCRv97/sys/os/glnxa64:$FREESURFER_HOME/MCRv97/extern/bin/glnxa64
-----
MACOS:
-----
... setup the freesurfer environment - here using bash shell ...
$ bash
$ export FREESURFER_HOME=/Applications/freesurfer/8.0.0
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-macOS-<OS_ARCH>-8.0.0-20250205-0f2bd3a --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /Applications/freesurfer/8.0.0
FSFAST_HOME /Applications/freesurfer/8.0.0/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /Applications/freesurfer/8.0.0/subjects
MNI_DIR /Applications/freesurfer/8.0.0/mni
... install either the Matlab R2014b or R2019b runtime environment ...
$ which fs_install_mcr
/Applications/freesurfer/8.0.0/bin/fs_install_mcr
$ sudo FREESURFER_HOME=$FREESURFER_HOME $FREESURFER_HOME/bin/fs_install_mcr R2019b
<output deleted>
... set LD_LIBRARY_PATH to point to The Mathworks libraries ...
$ export LD_LIBRARY_PATH=$FREESURFER_HOME/MCRv97/runtime/maci64:$FREESURFER_HOME/MCRv97/bin/maci64:$FREESURFER_HOME/MCRv97/sys/os/maci64:$FREESURFER_HOME/MCRv97/extern/bin/maci64
================================================
ENABLE PYTHON PACKAGES TO UTILIZE NVIDA HARDWARE
================================================
*** ONLY FOR LINUX PLATFORMS WITH NVIDIA GRAPHICS HARDWARE ***
We include the CPU version of some python packages and not the GPU enabled version because of package, licensing and re-distribution issues. Once freesurfer is installed, you can change the included python distribution to instead use the GPU versions of some packages by running the following script.
To update to the GPU enabled version of torch, run the following,
$ sudo FREESURFER_HOME=$FREESURFER_HOME $FREESURFER_HOME/bin/fs_install_cuda
Replace torch 2.1.2+cpu with torch 2.1.2 in /usr/local/freesurfer/8.0.0-1/python? (y/n): <----- answer yes by typing "y"
... torch and some other packages will be updated along with downloading various nvidia packages ....
... please wait for the updates to finish and look for the success message ...
<output deleted>
cuda install success