# FreeSurfer: turning structural MRI into surfaces, labels and group statistics

> FreeSurfer is a neuroimaging analysis suite from the Martinos Center at MIT that provides full processing streams for structural and functional MRI, covering registration, cortical and subcortical segmentation, surface reconstruction, group morphometry, diffusion MRI and PET analysis. It is C++ software with a per-user licence file, a wiki as its manual, and a mailing list archive as its support desk.

**freesurfer/freesurfer** — Neuroimaging analysis and visualization suite

- Repository: https://github.com/freesurfer/freesurfer
- Stars: 881 · Forks: 303
- Language: C++
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/freesurfer-freesurfer

## The problem: getting from a structural MRI to a labelled surface

A structural brain MRI is a stack of volumes. Turning that into something a neuroscientist can measure, compare across subjects and put into a publication means a long chain of work: motion correction, intensity normalisation, tissue segmentation, surface reconstruction, spherical registration for cross-subject comparison, and a set of statistics on the result.

FreeSurfer is a software package for the analysis and visualization of neuroimaging data from cross-sectional and longitudinal studies, and it provides full processing streams for structural and functional MRI rather than a set of disconnected tools. It is developed by the Laboratory for Computational Neuroimaging at the Martinos Center for Biomedical Imaging.

The audience is imaging researchers, and the strongest signal about its standing is the last clause of the project description: it is also the structural MRI analysis software of choice for the Human Connectome Project. A pipeline used for a large multi-site study has to be reproducible across machines and years, and that requirement shapes a lot of the software's design.

The primary language is C++, which is worth noting for anyone planning to build it. The repository is enormous in both scope and line count, the top-level directory listing runs to more than fifty entries, and the build is a CMake project with a build guide in the wiki.

The default branch is dev, the last push was on 2026-10-19, and the project publishes no GitHub releases.

## What the package covers, from registration to morphometry

The feature list in the project description is dense and specific, and it is the clearest statement of scope.

FreeSurfer provides full processing streams for structural and functional MRI, and includes tools for linear and nonlinear registration, cortical and subcortical segmentation, cortical surface reconstruction, statistical analysis of group morphometry, diffusion MRI, PET analysis, and much more.

The order of that list is the pipeline order, and it explains the design. Registration comes first because everything downstream is defined relative to a common space. Segmentation follows, because the parcellation defines both the surfaces and the statistics. Surface reconstruction turns the segmentation into a folded representation that can be registered spherically, which is what makes group morphometry possible, since cortical area and thickness are measured on a common spherical template rather than in voxel space. Diffusion MRI and PET analysis are separate but related streams.

That last point is the one that catches newcomers. Group morphometry is not a general statistics module bolted onto an imaging tool, it is the reason the surface reconstruction exists, and the two are coupled through the spherical registration.

The visualisation side is a separate program rather than part of the pipeline. The repository has a freeview/ directory, which is the interactive viewer for surfaces, volumes and annotations, and the project description calls the whole thing an analysis and visualization suite.

For documentation, the project points at the FS Wiki for expansive documentation on using and understanding the FreeSurfer tools, and the wiki is where the tutorial material lives.

## The repository shape, one directory per processing stream

The top-level directory listing is the clearest available map of the software, and it is organised by processing stream rather than by library.

There are the classic FreeSurfer streams in their own directories, including AANsegment/ for automatic anatomical segmentation, AntsDenoiseImageFs/ and AntsN4BiasFieldCorrectionFs/ for the two intensity normalisation steps, and the surface reconstruction tools hiam_make_surfaces/, hiam_make_template/ and hiam_register/. There are the newer analysis directories, among them ThalamicNuclei/ and ThalamicNucleiDTI/ for thalamic nuclei, HippoSF/ for hippocampal analysis, anatomicuts/ for anatomical cuts of diffusion data, and cnn_sphere_register/ for spherical registration with a convolutional network.

There is also a long tail of specific pipelines, such as diabetes/, fem_elastic/, exvivo/, infant/, dmri_poistats/, histo_compute_joint_density/, histo_register/, histo_synthesize/, label2flat/, label2patch/ and lineprof/. Several of these names correspond to published methods, which tells you the repository has grown by absorbing one study's pipeline at a time.

The shared infrastructure sits in include/, io/, itkio/, itkutils/, cmake/, docs/ and distribution/, and the build is driven by the CMakeLists.txt at the root, with a Doxyfile for the API documentation.

Two directory names are worth explaining because they will confuse a reader who has not used the software. The attic/ directory is where historical or superseded code is parked, and dummy/ and dummy_qt/ are test and placeholder trees rather than real functionality.

The result is a codebase that is best read as a collection of pipelines sharing a common substrate, not as a library with an API. That is the right shape for the problem, and it is also why the wiki rather than the source is where you start.

## The licence file, and the registration form behind it

FreeSurfer is not distributed under a standard open source licence. The repository records the licence as a custom one that GitHub cannot classify, and the terms and conditions for use, reproduction, distribution and contribution are found in LICENSE.txt.

The Docker instructions show what that means in practice. Users are expected to fill out the registration form on the project site to download a license.txt file that arrives by email, and they can then copy that file to live under $FREESURFER_HOME as .license. Alternatively, the file can be placed anywhere inside the container and the FS_LICENSE environment variable set to point at it, which means the licence file is always found even if you install or remove other FreeSurfer distributions.

So the adoption decision has a step that a typical open source project does not have: you register, you receive a file, and that file has to travel with your installation. The environment variable route is the one to prefer if you build images, because it decouples the licence from the directory layout.

This is not the same as a restrictive proprietary licence, and the project does describe itself as open source, but for an organisation that runs a licence audit, a per-user file obtained by email is a different process from a package manager resolving an MIT dependency, and it is worth knowing about before you commit a build pipeline to it.

## The container image, and the limit it states about itself

The Dockerfile builds a container with the FreeSurfer 7.2.0 release from 07/2021, and its first comment is the most useful line in the file: installs which do not use the Linux packaging tools, to install via an .rpm or .deb file, are not officially supported.

That is a careful warning. The image is built from centos:7, installs the system packages the suite needs, including bc, libgomp, perl, tar, tcsh, wget, vim-common and the Mesa and X libraries, then downloads the FreeSurfer tarball from the project distribution directory, unpacks it into /usr/local and removes the archive.

The environment is set up carefully, with FREESURFER_HOME pointing at the install and the PATH extended to include the bin, fsfast/bin, tktools and mni/bin directories, because the individual tools expect to find each other in those places.

What the image is for is therefore a convenience and a reference, not the supported installation path. The supported paths are the Linux packaging tools, and the image is pinned to a 2021 release on a base image that is long past its own end of life, which is worth knowing before you build a pipeline on it.

For a newcomer, the practical advice is to use the packaged installation for the version you intend to run, and to treat the container as a way to try the suite without touching the host, with the licence file pointed at by the FS_LICENSE variable.

## Getting help, and where the answers actually live

The support section of the project documentation is short, and its advice is about where to look rather than where to file things.

The first step is to search the archives. It is highly likely that someone else has run into the same problem before, and the fastest way to get answers is to search the archives of the project's mailing list, which are hosted on mail-archive.com. The second step is to subscribe to the mailing list and start a discussion, at the listinfo address on the project's own mail server.

Only after that does the issue tracker come into it. If you have found a bug in the software, you can open an issue or submit a patch, after reviewing the CONTRIBUTING.md documentation.

That order is a good description of how the project actually works. The software is old enough, and used widely enough, that the mailing list is the accumulated knowledge base, and the wiki is the manual. The repository is where the code lives and where the contribution guide explains the development conventions, not where you would look up how to run a specific command.

For developers, the project points at the contribution guidelines and the build guide, which has step-by-step instructions on configuring and building the source code.

## Where FreeSurfer is the wrong tool

The boundaries are mostly about scale and about the licensing step.

If you have a handful of subjects and a simple question about one anatomical region, FreeSurfer is an enormous commitment. The surface based pipeline is designed for group analysis, it is slow, it needs a Linux workstation with enough memory and disk for the intermediate files, and the results depend on getting the version and the configuration right for your study. A conventional volumetric toolchain is the better answer for a one-off.

If your images are functional rather than structural, or your modality is diffusion or PET, the fit depends on the specific stream, and the project documentation lists PET analysis and diffusion MRI as included, but the structural pipeline is the one that is described as the tool of choice for the Human Connectome Project, so that is where the maturity is.

And if your organisation cannot accommodate a per-user licence file obtained by email, that is a procurement conversation to have before you build anything, not after.

What FreeSurfer gives you is a pipeline that a large consortium has standardised on, with the wiki as the manual and the mailing list as the archive of what has already gone wrong. The judgement is that for a research group running a structural MRI study, that combination is worth the setup, and for anyone else, the cost of entering is higher than the cost of the alternative.

## Conclusion

Adopt FreeSurfer if you are processing structural or functional MRI in a research setting and need the standard surface based pipeline that the Human Connectome Project uses, and if you can run a Linux workstation with a compiler for the pieces you need to build. Do not adopt it for a one-off analysis where a lighter tool will do, and do not assume the container image is a supported installation path, since the Dockerfile says installs that do not use the Linux packaging tools are not officially supported. Before you start, complete the registration form for the licence file, read the build guide, and plan for the fact that the wiki and the mailing list archives, not the repository, are where the answers live.

## FAQ

### What is FreeSurfer used for?

It is a software package for the analysis and visualization of neuroimaging data from cross-sectional and longitudinal studies, providing full processing streams for structural and functional MRI, including linear and nonlinear registration, cortical and subcortical segmentation, cortical surface reconstruction, group morphometry statistics, diffusion MRI and PET analysis.

### Who develops FreeSurfer and who uses it?

It is developed by the Laboratory for Computational Neuroimaging at the Martinos Center for Biomedical Imaging, and it is the structural MRI analysis software of choice for the Human Connectome Project.

### How does the FreeSurfer licence work?

The repository licence is a custom one that GitHub cannot classify, with the terms for use, reproduction, distribution and contribution in LICENSE.txt. The Docker instructions expect you to fill in a registration form to receive a license.txt file by email, then store it as .license under $FREESURFER_HOME or point the FS_LICENSE environment variable at it.

### Is the FreeSurfer Docker image the supported way to install it?

Not according to the Dockerfile, which notes that installs which do not use the Linux packaging tools, to install via an .rpm or .deb file, are not officially supported. The image is pinned to the 7.2.0 release from 2021 and is built on centos:7.

### Where should I look for help with FreeSurfer?

The documentation points first at the archives of the project's mailing list, which is described as the fastest way to get answers, then at subscribing to the list to start a discussion. Issues and patches go to the GitHub tracker after reading CONTRIBUTING.md, and the FS Wiki carries the extensive usage documentation.

## Sources

- [freesurfer/freesurfer on GitHub](https://github.com/freesurfer/freesurfer)
- [Issues](https://github.com/freesurfer/freesurfer/issues)
- [README](https://github.com/freesurfer/freesurfer/blob/dev/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/freesurfer-freesurfer