Linux Install & Setup

CentOS 7 and 8

The examples below show how to unpack the Freesurfer 7.0.0 CentOS 7 tar archive, freesurfer-linux-centos7_x86_64-7.0.0.tar.gz, or how to install the rpm file, freesurfer-CentOS7-7.0.0-1.x86_64.rpm. The freesurfer CentOS7 RPM installer and archive package can also be used on CentOS8. Please note the instructions are a bit different for using the RPM in the CentOS8 section compared to the CentOS7 section.

CentOS 6

If you are still working with CentOS 6 (which will no longer be supported by CentOS after November 2020), then you would use the same commands in the examples below, but instead use the CentOS6 archive freesurfer-linux-centos6_x86_64-7.0.0.tar.gz or rpm file freesurfer-CentOS6-7.0.0-1.x86_64.rpm. instead of the CentOS7 files.

Ubuntu 18

Use the CentOS7 example below where the tar archive is unpacked on a CentOS7 system - and do the same on your Ubuntu system. We hope to provide an Ubuntu .deb installer in the near future.

On Linux 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., /usr/local, you will typically need sudo or root privileges. Please note that if you have sudo/root privileges, then we recommend trying the RPM file (.rpm) to installer. The linux package management tools provide the advantage of trying to install any software packages freesurfer depends upon that are not already installed on your system as part of installing freesurfer under /usr/local/freesurfer/<package version>.

Example of placing the CentOS7 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-linux-centos7_x86_64-7.0.0.tar.gz
x freesurfer/
x freesurfer/WMParcStatsLUT.txt
x freesurfer/sessions/
x freesurfer/sessions/README
...
..
<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-linux-centos7_x86_64-7.0.0-20200427-5b17a0d --------
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 CentOS7 tar archive under the system location /usr/local by user "tester" using sudo/root privileges. Setup commands follow. Shell is bash or Bourne shell.

$ cd $HOME
$ pwd
/home/tester
$ sudo tar -C /usr/local -zxvpf freesurfer-linux-centos7_x86_64-7.0.0.tar.gz
x freesurfer/
x freesurfer/WMParcStatsLUT.txt
x freesurfer/sessions/
x freesurfer/sessions/README
...
..
<rest of output deleted>

$ export FREESURFER_HOME=/usr/local/freesurfer
$ export SUBJECTS_DIR=$FREESURFER_HOME/subjects
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-linux-centos7_x86_64-7.0.0-20200427-5b17a0d --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME   /usr/local/freesurfer
FSFAST_HOME       /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /usr/local/freesurfer/subjects
MNI_DIR           /usr/local/freesurfer/mni

$ which freeview
/usr/local/freesurfer/bin/freeview

Using the Yum Linux Package Manager (RedHat/CentOS)

The "yum" package manager command is available on Redhat/CentOS linux and its derivatives to install, manage, and update the system software. System packages in the form of *.rpm files may contain source, binaries and/or libraries to install on the system. The *.rpm package also usually contains a list of the system libraries and programs the *.rpm package contents will need from the system in order to run after installation. Yum compares the system dependency information in the *.rpm package against what is currently installed on the system. Then it determines what if any other *.rpm packages need to be downloaded and installed in order to satisfy the dependencies for the package(s) you have listed to install on the command. Depending upon what is already installed on your system, yum will figure out what if any system software is missing, and then install it for you if granted permission. Hence the builtin yum/RPM tools can save you the hassle of trying to figure out what software is missing on your system before you attempt to install and run freesurfer.

CentOS 6 and 7 RPM install.

CentOS 8 RPM install.

The "yum" package manager command is available on Redhat linux and its derivatives (like CentOS) to install, manage, and update the system software. System packages in the form of *.rpm files may contain source, binaries and/or libraries to install on the system. The *.rpm package also usually contains a list of the system libraries and programs the *.rpm package contents will need in order to run after installation. Yum compares the system dependency information in the *.rpm package against what is currently installed on the system. Then it determines what if any other *.rpm packages need to be downloaded and installed first in order to satisfy the dependencies in the package(s) you have listed on the yum install command line.

Yum will present a list of all packages it determines should be installed before installing the packages you ask for. You can accept or refuse to install the list of packages yum provides. Answering no ("N") to yum will cause no software to be installed and leave the system unchanged.

Exploring the broad range of yum command line options is beyond the scope of this freesurfer install example. Note that a non-privileged user not doing an install can run yum (and rpm) commands without sudo and see what is installed on the system, what packages are available from the online repos, etc.

If the yum command has not been run in a while, the first thing it will do is update the list of packages available from the online repositories on the web it uses to search for and download packages from. If we ask yum to tell us if freesurfer is already installed, you might see output like this from yum reporting it is updating the list of available packages and the sites to fetch them from.

$ yum list installed | grep -i freesurfer
updates
(1/2) epel/x86_64 updateinfo
(2/2) updates/7/x86_64/primary_db
...
.. <output deleted / your output will vary>
.
Determining fastest mirrors
* base: mirror.siena.edu
* epel: ewr.edge.kernel.org
...
.. <output deleted / your output will vary>
.
$

The result of the above command is that nothing was printed out listing an installed freesurfer package and its version number. Or in the example below, the assumption is that no freesurfer package is currently installed on the system.

We provide a freesurfer *.rpm package for download that is not part of an existing Redhat, CentOS or third-party repository. Yum by default assumes a package is available from an existing online collection of pakcages it has been configured to search for. So in response to the most basic command to install a "freesurfer" package, yum will search through every repository it knows about, find nothing, and then give up.

$ sudo yum install freesurfer
Loaded plugins: fastestmirror, langpacks
Loading mirror speeds from cached hostfile
 * base: mirrors.seas.harvard.edu
 * epel: mirrors.mit.edu
 * extras: mirror.san.fastserv.com
 * rpmforge: repoforge.spinellicreations.com
 * updates: mirrors.mit.edu
..  <your output will vary>
No package freesurfer available.
Error: Nothing to do
$

The remedy is to provide command line options to tell yum: (1) the package is not signed as it would be in an online repository; (2) the freesurfer rpm package is local to the machine and should not be searched for or downloaded from an online repository.

$ sudo yum --nogpgcheck localinstall freesurfer-CentOS7-7.0.0-1.x86_64.rpm

Previewing the install

The screen shots below show what the yum package manager reports should be installed for a particular machine running CentOS 7.4. Typing "N" will cancel the install of all software. At the time of this writing, the current revision of CentOS is 7.7. So if you are running a newer version of CentOS compared to CentOS 7.4, and you already have packages like the gcc tools installed on your system, then yum will likely report fewer packages need to be updated and/or installed prior to installing the freesurfer package.

Cos7_preinstall_1_4.png

Cos7_preinstall_2_4.png

Cos7_preinstall_3_4.png

Cos7_preinstall_4_4.png

Performing the install

The screen shots below show what the yum package manager reports has been installed on the system after the install is accepted.

Please note - if you already have freesurfer installed as /usr/local/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 /usr/local. This is because the rpm installer will install freesurfer under the path /usr/local/freesurfer/<package version>

Cos7_install_1_4.png

Cos7_install_2_4.png

Cos7_install_3_4.png

Cos7_install_4_4.png

Verifying the install & Setup

We can ask yum again if freesurfer is installed - and this time the answer should be yes. Note that freesurfer was installed under /usr/local/freesurfer in a subdirectory that matches the package revision yum lists as installed on the system. Subsequent freesurfer rpm packages with higher revision numbers will be recognized by yum as upgrades to be installed on the system.

install_verify.png

Setting the environment follows the same procedure as listed above except the path for FREESURFER_HOME is now /usr/local/bin/freesurfer/7.0.0-0.1.b1.

Cos7_setup_verify.png

Finally, a simple test to see if the freeview application can load a volume.

Cos7_try_freeview.png