fMRIPrep: reproducible fMRI preprocessing with BIDS input and a visual report per subject

What fMRIPrep does, and the deliberate ceiling on what it does

fMRIPrep is a functional magnetic resonance imaging data preprocessing pipeline designed to give an easily accessible, state-of-the-art interface that tolerates variations in scan acquisition protocols and needs minimal user input, while giving interpretable error and output reporting. In plain terms, it takes raw scanner data organised in BIDS and produces data you can hand to a group level analysis.

What it does to that data is spelled out in a note in the README, and the list is short. Minimal preprocessing is defined as motion correction, field unwarping, normalization, bias field correction and brain extraction. The broader list of processing steps given elsewhere includes coregistration, unwarping, noise component extraction, segmentation and skull-stripping.

That definition is the most important thing to understand before you install anything. This is not a pipeline that denoises, regresses, smooths, resamples to a study template of your choice and hands you a finished statistical map. It does the standard spatial and motion corrections and stops there. What you do next, including nuisance regression and any decision about smoothing, is your analysis, not the preprocessing.

The audience is researchers who already speak the BIDS vocabulary, since the pipeline's dependence on that standard is what allows manual parameter input to be reduced to a minimum. If your data is not in BIDS, the first job is conversion, and the pipeline is not the tool for that job.

NiPreps, Nipype and a stack of imaging tools underneath

fMRIPrep is a NiPreps application, and the family resemblance shows in the dependency list. The Python package metadata names the authors as The NiPreps Developers, and the dependencies pull in the sibling projects that do the actual imaging work: niworkflows for the shared workflow templates, sdcflows for susceptibility distortion correction, nitransforms for spatial transforms, templateflow for templates, tedana for the noise component analysis, and smriprep, which is pinned to a git reference rather than a version, from the master branch of its own repository.

Underneath those sits Nipype, the workflow engine, plus the Python data stack: nibabel for image IO, pybids for reading the BIDS dataset, numpy and pandas for the tables, and requests for network access. nireports is what produces the visual report, and nireports is also what produces the citation boilerplate.

The imaging itself comes from established packages. The README says the pipeline uses a combination of tools from well-known software packages, including FSL, ANTs, FreeSurfer and AFNI, and that this was done to provide the best software implementation for each state of preprocessing, with updates as newer neuroimaging software becomes available. That is the design philosophy in one line: fMRIPrep is the orchestration and the policy, not the algorithms.

Two dependencies deserve a mention because they say something about what the pipeline does with your compute. codecarbon is listed, which points to accounting for the carbon cost of the run. APScheduler is also listed, which brings scheduling into the picture for long or repeated jobs. Neither is the main event, but both show a pipeline built with the operational realities of cluster use in mind.

Getting it installed: Python 3.12, a container image, or a source build

The packaging tells you what the environment has to look like. The project metadata declares its licence as Apache-2.0 with the LICENSE file as the licence file, and it sets a hard Python floor:

license = "Apache-2.0"
license-files = ["LICENSE"]
requires-python = ">=3.12"

The classifiers list Python 3.12, 3.13 and 3.14, and the development status is recorded as Production/Stable with an audience of Science/Research. A Python 3.11 workstation cannot run this.

The supported distribution route is the container image, which is why the repository has a Dockerfile, a Dockerfile.base, a Dockerfile_devel, a docker directory and a wrapper directory. The image is built on a pixi environment that the Dockerfile comment describes in detail: Python with the scientific stack from conda-forge, NodeJS carrying bids-validator and svgo, FSL from fslconda, ants and connectome-workbench from conda-forge, and more. The base image is pinned by argument:

ARG BASE_IMAGE=ghcr.io/nipreps/fmriprep-base:20251006

FROM ghcr.io/prefix-dev/pixi:0.78.0 AS build

That pinned tag is the single most consequential line in the repository for reproducibility. The neuroimaging software versions your results depend on are baked into the base image, so two groups running different base image tags can get different outputs from identical inputs. The Makefile at the root offers a docker-build target that pulls the base image or builds it from Dockerfile.base, then builds the application image with the build date, the VCS reference and the version passed in as build arguments.

For a first run, the practical sequence is to pull the published image from the Docker Hub tags listed in the project metadata, point it at a BIDS dataset directory, and read the report it produces. The README does not give a command line for this, so the invocation flags have to come from the documentation at fmriprep.org rather than from the repository README.

The glass box report is the actual quality control mechanism

The third of the project's three principles is called the glass box philosophy, and the README states it plainly: automation should not mean that one should not visually inspect the results or understand the methods. The second principle is ease of use, and the first is adaptation of the preprocessing steps to the input dataset.

The mechanism that follows from this is the visual report. fMRIPrep generates preprocessing quality reports for each subject, and the README describes the intended use as letting the user easily identify outliers. The report details the accuracy of the most important processing steps, and combined with the documentation it is meant to help researchers decide which subjects should be kept for group level analysis. That is a substantive design choice, because the alternative to inspecting a report is trusting a pipeline blindly, and the report is generated for every subject processed rather than on request.

The same automation carries the citation requirement. Every subject's report includes citation boilerplate, the README asks users to acknowledge the work using that boilerplate, and it recommends reproducing the text verbatim in published work. The boilerplate itself is public domain under the CC0 license, and the README gives a specific reason for reproducing it exactly: if reviewers or editors raise concerns because the text is flagged by automated plagiarism detection, they can be pointed at the NiPreps documentation on the topic. That is a small piece of process engineering that saves an argument with a reviewer.

The machine-readable side of the reporting is nireports, listed as a dependency, which is how the HTML report is produced rather than hand-assembled.

Where fMRIPrep stops, and where the alternatives start

The clearest boundary is the minimal preprocessing definition. If your analysis plan needs denoising beyond the noise component extraction the pipeline performs, or needs smoothing, or needs a specific template or resampling grid, that work is downstream of fMRIPrep and belongs in your own scripts.

The second boundary is the input format. Everything about the design follows from the dependence on BIDS: the pipeline reduces manual parameter input to a minimum because the dataset description carries the acquisition parameters. A lab with an archive of DICOM files and no BIDS conversion step has a project ahead of it, and a group of scanner operators who each keep their own naming conventions will get different results from the same brain.

On alternatives, the meaningful comparison is with the underlying packages and with the sibling project in the same family. FSL, ANTs, FreeSurfer and AFNI are the components fMRIPrep drives, and running them by hand is the alternative of last resort because that is exactly the manual, shell-scripted path the project claims to replace. The adjacent NiPreps tool is sMRIPrep, which appears in the dependency list as the source of anatomical MRI processing that fMRIPrep consumes for coregistration and spatial normalisation, so a group that only has anatomical T1 data has a separate entry point rather than a stretch of this one.

The third alternative is a different pipeline that is not part of the NiPreps framework. The README states that fMRIPrep adheres to the general licensing guidelines of the NiPreps framework, which frames the project as one implementation inside a family with a shared policy on licensing, citation and transparency. Choosing outside that family is legitimate, but you lose the shared conventions, and the project makes no claim to be the only defensible option.

Release cadence, the LTS line, and who maintains it

The release history shows a project with a steady hand. Version 25.2.3 LTS was published on 2025-10-31, 25.2.4 LTS on 2026-01-14 and 25.2.5 LTS on 2026-03-10. The LTS suffix in the release names signals that the 25.2 series is the line intended for production use, and the roughly two month gap between them is what a maintenance release cadence looks like in a project that also has to track new versions of Python, of Nipype and of the neuroimaging tools it drives.

Activity on the repository is current: the last push to the master branch was on 2026-10-19, with the default branch named master and the project also carrying a .versions.json file, a CHANGES.rst file and a pixi.lock file for the environment. The repository includes a Makefile, tox.ini, a .pre-commit-config.yaml and a .circleci directory, so continuous integration and local checks are both part of the workflow rather than optional extras.

Licensing is worth reading carefully because it changed. The README notes that as of the 21.0.x pre-release and release series fMRIPrep is licensed under Apache-2.0, matching the licence field in the project metadata, and it states that the project follows the general licensing guidelines of the NiPreps framework. The container image is a slightly different matter: the Dockerfile at the root of the repository carries an MIT License header, so the image distribution and the application code sit under different terms. That is a factual reading of two files, and any redistribution in your own image should be checked against both, plus the licences of FSL, ANTs, FreeSurfer and AFNI inside it, which are not covered by either header.

Editorial conclusion

fMRIPrep is the right tool for a neuroimaging group that already organises data in BIDS and wants preprocessing that another lab can reproduce, with per-subject visual reports and an automated outlier check rather than a hand-tuned shell script. It is the wrong tool for anyone hoping for a complete analysis, since the pipeline states that it performs minimal preprocessing, and for anyone without the compute budget, because the container image bundles FSL, ANTs, FreeSurfer, AFNI and a Node toolchain into every run. Before adopting, read the workflows page for the exact definition of minimal preprocessing, then check the Python floor in pyproject.toml, which requires 3.12 or newer, and the pinned base image argument in the Dockerfile, since the image tag in the repository pins the scientific software versions your results depend on.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nipreps/fmriprep on GitHub
3. Project website
4. README
5. Releases