HCP Pipelines: the MRI processing chain behind the Human Connectome Project

A published preprocessing recipe, expressed as scripts

The HCP Pipelines product is a set of tools, primarily but not exclusively shell scripts, for processing MRI images for the Human Connectome Project. The scripts implement the Minimal Preprocessing Pipeline, the MPP, described in Glasser and colleagues' 2013 paper.

That last point is the one that matters for an evaluation. This is not a new algorithm proposed by the repository; it is an implementation of a published recipe, and the paper is the specification. A group that wants its data preprocessed the way HCP data was, with the same distortion correction, the same registration and the same surface pipeline, is the audience. A group that wants a good general fMRI preprocessing for one dataset is not, because there are toolboxes for that which assume far less setup.

The project comes from Washington University, the default branch is master, the primary language of the repository is Shell, and the homepage is humanconnectome.org. The licence is one GitHub cannot classify, with the terms in a LICENSE.md file at the root, which is worth reading if you intend to redistribute the scripts inside a commercial environment.

The version history shows a large project with a slow release cadence. The tags are v6.0.0 on 2026-08-24, v5.0.0 on 2024-12-02 and v4.8.0 on 2024-06-20. A major version every year or two, with the last push to the repository on 2026-10-16.

One directory per processing stage, and a shared global configuration

The top-level listing is the clearest available picture of how the pipeline is organised, and it reads as a sequence of named stages rather than a single program.

There are directories for FreeSurfer, PreFreeSurfer, PostFreeSurfer, DeDriftAndResample, TransmitBias, GenerateSpinEchoBiasFieldPrereqs, fMRIVolume, fMRISurface, RestingStateStats, TaskfMRIAnalysis, DiffusionPreprocessing, bedpostx, MMORF, ICAFIX, MSMAll, MSMConfig, tICA, Supplemental, Examples, global, docs and Scripts under Examples.

The names describe the chain. A structural MRI path runs through FreeSurfer and the PreFreeSurfer and PostFreeSurfer stages, with DeDriftAndResample and the bias field and transmit bias directories handling the field-map corrections that structural processing needs. A functional path runs through fMRIVolume and fMRISurface with RestingStateStats and TaskfMRIAnalysis for the statistics. Diffusion has its own directory alongside bedpostx, which is the name of a well-known diffusion model fitting tool, and MMORF is the multi-modal orientation registration stage. The spin-echo directories address the bias fields that multi-echo acquisitions need.

The global/ directory is the one to look at first if you want to understand the configuration, because a pipeline with this many stages needs the settings, the paths and the tool versions resolved in one place rather than repeated. The docs/ directory and the Examples/Scripts directory cover the documentation and the worked examples, and the Examples/fsf_templates directory suggests the project ships its own FreeSurfer template material rather than expecting the user to source it.

A show_version script sits at the root, which is what a long-running pipeline needs when the version determines which third-party tool versions are expected.

An environment file at the root, and why that is the whole story

The environment.yml file at the repository root is the most consequential entry in that listing, because it means the pipeline is delivered as a defined computational environment rather than as a set of scripts you run against whatever happens to be installed.

That is the right shape for a pipeline like this. The chain calls FreeSurfer, a diffusion model fitting tool, registration software and a set of statistics tools, and each of those has its own build, its own version and its own opinions about libraries. A pipeline that pins the environment has a reproducible result; a pipeline that assumes the environment has drifted produces results that differ from the ones in the paper, and in neuroimaging those differences are the kind that end up in a methods section.

The cost is that adopting this is an environment problem as much as a pipeline problem. You are installing a specific set of neuroimaging software, which is a large download and a non-trivial dependency resolution, and the scripts will expect the tools to be found where the environment puts them.

The primary language being Shell is worth reading alongside this. Shell scripts are the right choice for a chain of command-line tools, because each stage is a sequence of external programs with a defined input and output, and a shell script for that is both short and readable by a person who knows the tools. The cost of that choice is that the pipeline has no type system and no unit tests to speak of, so a stage that fails usually fails with a message from the underlying tool rather than from the pipeline itself.

Where to get it, and where the documentation actually lives

There is no install command in the repository readme, and that is not an omission. The readme is a short pointer document, and it directs the reader to three places.

The first is the Release Notes, Installation, and Usage document for the current release, which is linked to the project wiki at the Installation-and-Usage-Instructions page. The second is the FAQ. The third is the wiki itself, which carries the rest of the documentation.

That structure is normal for a scientific pipeline, where the installation instructions are long, version-specific and change with every release, so they live in a wiki page that is revised rather than in a readme that is frozen in the repository. It also means the readme cannot be read on its own to decide whether to adopt the project, and the wiki has to be consulted.

For questions and discussion, the readme points to the hcp-users discussion list, a Google Group, with instructions for joining without a Google account, and a separate wiki page covers the join process. So the community channel is a mailing list rather than an issue tracker or a chat server, which is a reasonable fit for a user base that is largely research groups running long analyses rather than developers shipping code.

The practical sequence for an adopter is therefore: read the wiki installation document for the release you intend to use, set up the environment from environment.yml, and check the version with the show_version script before you submit a long job.

Where HCP Pipelines is the wrong choice

The first limitation is compute. This is a pipeline for processing MRI images, and processing MRI images means reconstructing surfaces, fitting diffusion models and running registration over volumes that are hundreds of megabytes each. The scripts are cheap, but what they call is not, and a group that has never run a surface reconstruction pipeline should expect the first end-to-end run to take a long time and to need storage.

The second is that it is a specific pipeline rather than a general one. The Minimal Preprocessing Pipeline was designed for the Human Connectome Project's acquisition protocol, with its particular echo times, its particular field maps and its particular sequence parameters. The scripts are configurable, but a dataset acquired with a different protocol will need those configurations revisited, and the defaults will not be right for it. A project with a handful of subjects and a standard acquisition is usually better served by the general-purpose toolkits, which make fewer assumptions about what your data looks like.

The third is the documentation shape. For a project with this much operational surface, having the installation instructions in a wiki rather than in versioned files in the repository is a real friction point. A wiki page can be edited by anyone with access, it is not diffed in a pull request, and it is not tied to a tag. When a release moves from v5.0.0 to v6.0.0, the question of which instructions applied to which version is answered by the release notes document rather than by the state of the repository at that tag.

The fourth is the licence. GitHub cannot classify it, and the metadata records it as a custom licence rather than naming a standard one. For a project that came out of a large academic consortium, a custom licence is not surprising, and it may well be permissive, but it is a licence a legal team has to read rather than recognise, and that is a small cost on the way to adoption.

The fifth is the shell scripting itself. Every stage is a command line program, which makes the pipeline transparent and easy to modify for a specific dataset, and also means a failure in stage nine of a two-day chain gives you a shell error and a log rather than a stack trace. For a pipeline whose stages are individually well understood, that is an acceptable trade. For a group that wants to modify the statistical stages rather than the geometric ones, the script-based approach offers less of a foothold than a library would.

Editorial conclusion

HCP Pipelines fits a neuroimaging group that wants its functional and structural MRI data preprocessed the way the Human Connectome Project data was, since the pipeline implements the published Minimal Preprocessing Pipeline and the whole chain is written as inspectable scripts rather than a black box. It is the wrong choice for a single dataset that a standard fMRI toolbox handles, and it is the wrong choice if you cannot supply the environment the scripts expect. Before running it, read the Release Notes, Installation, and Usage document in the project wiki and the FAQ, check the version with the show_version script, and note that the last push was on 2026-10-16 with the v6.0.0 release dated 2026-08-24.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Washington-University/HCPpipelines on GitHub