Ubuntu上安装FreeSurfer的详细流程

FreeSurfer是一个常用于结构MRI、功能MRI和扩散MRI分析与可视化的软件包。根据官方最新发布页，截至2026年3月，Linux侧当前可用的较新稳定版本包含8.2.0 ；对于Ubuntu，官方提供与系统匹配的.deb安装包，且官方明确更推荐使用.deb/.rpm安装器，而不是仅解压tar.gz，因为安装器会处理依赖，tar包更适合作为无管理员权限时的备选方案。官方还给出了8.x版本的内存建议：运行recon-all时建议系统总内存至少32GB。(FreeSurfer)

一、安装前说明

本文以Ubuntu22/Ubuntu24为例。官方当前8.2.0页面列出的Linux支持系统包括Ubuntu22和Ubuntu24，对应安装包分别为：

freesurfer_ubuntu22-8.2.0_amd64.deb
freesurfer_ubuntu24-8.2.0_amd64.deb

另外，FreeSurfer安装后必须配置license.txt 才能正常运行。

官方说明是：下载安装本身不需要注册码，但软件要真正运行，必须有license.txt。官方同时建议将license.txt放在用户主目录，并通过环境变量FS_LICENSE指向它。

二、完整命令汇总（Ubuntu24可直接复制）

bash 复制代码

# 1.安装常见依赖
sudo apt update
sudo apt install -y wget tcsh xxd build-essential gfortran \
    libblas-dev liblapack-dev zlib1g-dev \
    libxmu-dev libxmu-headers libxi-dev libxt-dev \
    libx11-dev libglu1-mesa-dev

# 2.下载FreeSurfer 8.2.0
cd ~/Downloads
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/8.2.0/freesurfer_ubuntu24-8.2.0_amd64.deb

# 3.安装
sudo dpkg -i freesurfer_ubuntu24-8.2.0_amd64.deb
sudo apt --fix-broken install -y

# 4.将license.txt放到主目录
mv ~/Downloads/license.txt ~/license.txt

# 5.配置环境变量
cat << 'EOF' >> ~/.bashrc
export FREESURFER_HOME=/usr/local/freesurfer/8.2.0
export FS_LICENSE=$HOME/license.txt
source $FREESURFER_HOME/SetUpFreeSurfer.sh
EOF

# 6.生效
source ~/.bashrc

# 7.验证
echo $FREESURFER_HOME
echo $FS_LICENSE
recon-all -version
which recon-all
which freeview

三、推荐安装方式：使用Ubuntu的`.deb`安装包

1）先更新系统并安装常见依赖

虽然.deb通常会处理主要依赖，但为了减少后续报错，建议先安装一些常见基础组件。官方构建依赖页面中，Ubuntu侧列出了如tcsh、wget、libxmu-dev、libx11-dev、libglu1-mesa-dev等库。

bash 复制代码

sudo apt update
sudo apt install -y wget tcsh xxd build-essential gfortran \
    libblas-dev liblapack-dev zlib1g-dev \
    libxmu-dev libxmu-headers libxi-dev libxt-dev \
    libx11-dev libglu1-mesa-dev

2）下载对应版本的安装包

如果你是Ubuntu24 ，下载8.2.0对应的.deb包即可：

bash 复制代码

cd ~/Downloads
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/8.2.0/freesurfer_ubuntu24-8.2.0_amd64.deb

如果你是Ubuntu22，则用：

bash 复制代码

cd ~/Downloads
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/8.2.0/freesurfer_ubuntu22-8.2.0_amd64.deb

3）安装FreeSurfer

Ubuntu24执行：

bash 复制代码

sudo dpkg -i freesurfer_ubuntu24-8.2.0_amd64.deb
sudo apt --fix-broken install -y

Ubuntu22执行：

bash 复制代码

sudo dpkg -i freesurfer_ubuntu22-8.2.0_amd64.deb
sudo apt --fix-broken install -y

根据官方8.x安装说明，Ubuntu安装后的默认目录可按/usr/local/freesurfer/8.2.0来配置环境变量。(FreeSurfer)

四、申请并配置license.txt

1）申请license

进入FreeSurfer官方注册页，填写姓名、机构和邮箱后，官方会把license.txt发到你的邮箱。官方说明写得很明确：没有license.txt，FreeSurfer无法完整运行 。

2）把license.txt放到主目录

假设你已经收到license.txt，建议放到当前用户主目录：

bash 复制代码

mv ~/Downloads/license.txt ~/license.txt

3）配置环境变量

编辑~/.bashrc：

bash 复制代码

nano ~/.bashrc

在文件末尾加入下面三行：

bash 复制代码

export FREESURFER_HOME=/usr/local/freesurfer/8.2.0
export FS_LICENSE=$HOME/license.txt
source $FREESURFER_HOME/SetUpFreeSurfer.sh

保存退出后执行：

bash 复制代码

source ~/.bashrc

五、验证是否安装成功

1）检查环境变量

bash 复制代码

echo $FREESURFER_HOME
echo $FS_LICENSE

正常情况下应分别输出类似：

bash 复制代码

/usr/local/freesurfer/8.2.0
/home/你的用户名/license.txt

2）检查版本

bash 复制代码

recon-all -version

或者：

bash 复制代码

which recon-all
which freeview

如果路径和版本都能正常输出，说明FreeSurfer基本安装完成。

3）加载环境时的正常提示

官方示例中，执行

bash 复制代码

source $FREESURFER_HOME/SetUpFreeSurfer.sh

后会打印类似FREESURFER_HOME、FSFAST_HOME、SUBJECTS_DIR、MNI_DIR等环境信息，这是正常现象。

六、可选：设置默认的SUBJECTS_DIR

FreeSurfer后续处理时通常会把被试结果放到SUBJECTS_DIR中。你可以单独指定一个更方便管理的数据目录，例如：

bash 复制代码

mkdir -p ~/freesurfer_subjects
nano ~/.bashrc

在末尾追加：

bash 复制代码

export SUBJECTS_DIR=$HOME/freesurfer_subjects

然后重新加载：

bash 复制代码

source ~/.bashrc

这样后续recon-all输出就会集中保存在这里，而不是软件安装目录内部。

七、快速测试一个最基础的命令

假设你有一个T1图像T1.nii.gz，可以用下面的命令做最基础测试：

bash 复制代码

recon-all -i T1.nii.gz -s sub001 -all

其中：

-i：输入T1图像
-s：被试名
-all：执行完整流程

需要注意的是，8.x版本官方说明提到新的recon-all流程相比旧版更快，但内存占用也更高，某些阶段可能会到较高内存使用水平；如果你的机器内存比较紧张，可以使用旧行为模式。

旧行为模式示例：

bash 复制代码

export FS_V8_XOPTS=0
recon-all -i T1.nii.gz -s sub001 -all

官方说明中，设置FS_V8_XOPTS=0后可以回退到8.x之前的旧式recon-all行为。

八、备选安装方式：tar.gz手动安装

如果你没有sudo权限，或者所在服务器不方便直接用.deb安装，也可以用官方提供的tar.gz包。官方明确说这是备选方案，因为tar解压不会自动检查和管理依赖，运行时出问题的概率更高。

1）下载tar包（以Ubuntu22上的7.4.1为例）

bash 复制代码

cd ~/Downloads
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/7.4.1/freesurfer-linux-ubuntu22_amd64-7.4.1.tar.gz

2）解压到指定目录

官方旧版Linux安装说明中推荐安装到/usr/local。如果你没有root权限，也可以解压到自己的hone目录。

有root权限时：

bash 复制代码

sudo tar -C /usr/local -xzvf freesurfer-linux-ubuntu22_amd64-7.4.1.tar.gz

无root权限时：

bash 复制代码

mkdir -p ~/software
tar -C ~/software -xzvf freesurfer-linux-ubuntu22_amd64-7.4.1.tar.gz

3）配置环境变量

如果解压到了~/software/freesurfer，则在~/.bashrc中加入：

bash 复制代码

export FREESURFER_HOME=$HOME/software/freesurfer
export FS_LICENSE=$HOME/license.txt
source $FREESURFER_HOME/SetUpFreeSurfer.sh

然后：

bash 复制代码

source ~/.bashrc

九、常见问题

1）执行`recon-all`提示找不到license

通常是下面几个原因：

没有收到或没有放置license.txt
FS_LICENSE没有正确设置
~/.bashrc修改后没有执行source ~/.bashrc

先检查：

bash 复制代码

ls -l ~/license.txt
echo $FS_LICENSE

官方推荐的标准做法就是把license放在主目录并设置：

bash 复制代码

export FS_LICENSE=$HOME/license.txt

2）执行命令提示`command not found`

说明FreeSurfer环境没有被加载。重新执行：

bash 复制代码

source ~/.bashrc

或者直接手动加载：

bash 复制代码

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

3）服务器上`freeview`打不开

这通常不是FreeSurfer没装好，而是图形界面环境没有配好，例如没有X11转发、没有桌面环境，或者显卡/OpenGL相关库有问题。FreeSurfer的命令行流程和freeview图形显示依赖并不完全相同；很多服务器场景下只跑recon-all即可，不一定需要直接打开freeview。

4）8.x版本内存占用太高

官方对8.x的说明里明确提到，新版recon-all更快，但会消耗更多内存；如果机器内存有限，可以尝试：

bash 复制代码

export FS_V8_XOPTS=0

再运行recon-all，使用旧版行为模式。

参考说明

FreeSurfer官方发布页：包含8.2.0的Ubuntu22/24安装包、系统支持范围、RAM要求以及"优先使用.deb/.rpm安装器"的建议。(rel7downloads)
FreeSurfer官方Linux环境配置页：给出了bash/sh下FREESURFER_HOME与SetUpFreeSurfer.sh的标准写法。(SetupConfiguration_Linux)
FreeSurfer官方license说明：明确说明软件运行需要license.txt。(FreeSurfer Registration form)
FreeSurfer 8.x官方说明：建议用FS_LICENSE指向$HOME/license.txt，并说明了8.x的recon-all新行为与FS_V8_XOPTS=0回退方法。(rel7downloads/rel8notes)

Ubuntu上安装FreeSurfer的详细流程

一、安装前说明

二、完整命令汇总（Ubuntu24可直接复制）

三、推荐安装方式：使用Ubuntu的.deb安装包

1）先更新系统并安装常见依赖

2）下载对应版本的安装包

3）安装FreeSurfer

四、申请并配置license.txt

1）申请license

2）把license.txt放到主目录

3）配置环境变量

五、验证是否安装成功

1）检查环境变量

2）检查版本

3）加载环境时的正常提示

六、可选：设置默认的SUBJECTS_DIR

七、快速测试一个最基础的命令

八、备选安装方式：tar.gz手动安装

1）下载tar包（以Ubuntu22上的7.4.1为例）

2）解压到指定目录

3）配置环境变量

九、常见问题

1）执行recon-all提示找不到license

2）执行命令提示command not found

3）服务器上freeview打不开

4）8.x版本内存占用太高

参考说明

三、推荐安装方式：使用Ubuntu的`.deb`安装包

1）执行`recon-all`提示找不到license

2）执行命令提示`command not found`

3）服务器上`freeview`打不开