Running fMRIPrep

This page describes fMRIPrep itself, independent of any particular computer. For submitting it as a batch job on the SCC, see Running fMRIPrep on the SCC.

The options below are those of fMRIPrep 25.2.5. Options change between releases — several were renamed in the 24.x and 25.x series — so check your own version with:

[scc4]$ fmriprep --help

The Basic Call

fMRIPrep takes three positional arguments, always in this order:

[scc4]$ fmriprep <bids_dir> <output_dir> <analysis_level>
Argument Meaning
bids_dir Root of a BIDS-valid dataset — the directory holding the sub-* folders.
output_dir Where the preprocessed derivatives and HTML reports are written.
analysis_level Always participant. See below.

A minimal run over a whole dataset:

[scc4]$ fmriprep /data/bids /data/bids/derivatives/fmriprep participant

Everything else is optional. In practice you will always want to set at least the performance options, because their defaults are unsafe on a shared machine — see Controlling Resources.

Only One Analysis Level

If you have used MRIQC, you will be used to running a participant pass and then a group pass. fMRIPrep has no group level. Its help text lists exactly one choice for the third argument:

{participant}         Processing stage to be run, only "participant" in the
                      case of fMRIPrep (see BIDS-Apps specification).

Every subject is preprocessed independently, which is what makes fMRIPrep a natural fit for a job array: there is no pooling step at the end and no ordering constraint between subjects.

Choosing What Gets Processed

By default fMRIPrep processes every subject and every BOLD series it finds. These options narrow that down.

Option What it does When to use it
--participant-label LABEL Process only the named subjects. The sub- prefix is optional. Testing on one subject before committing to the whole study; re-running the few that failed; splitting a dataset across parallel jobs.
--session-label LABEL Keep only these sessions. Longitudinal studies where you only care about one timepoint.
--task-id ID Keep only these functional tasks. A dataset with several tasks when you only need one preprocessed.
--bids-filter-file PATH A JSON file expressing an arbitrary PyBIDS query. Selection the flags above cannot express — a specific acquisition or run.
--anat-only Run the anatomical workflows and stop. Checking segmentation and normalization quickly, before spending hours on the functional runs.

Controlling Resources

Set these explicitly. Left alone, fMRIPrep sizes itself to the machine it appears to be running on, which on a shared or scheduled system means it will use cores and memory that were never allocated to it.

Option What it does When to change it
--nprocs N Maximum number of threads across all processes. Always. Match it to the cores your job was given.
--omp-nthreads N Maximum number of threads per process. Always.
--mem-mb N Upper bound on memory, in megabytes. Always. Match it to the memory your job was given.
--low-mem Reduce memory use at the cost of more disk in the work directory. A subject that keeps getting killed for memory and cannot be given more.

Watch the units. fMRIPrep's --mem-mb is in megabytes, so 32 GB is --mem-mb 32000. MRIQC's equivalent option takes gigabytes. Passing 32 here asks fMRIPrep to run in 32 MB.

The Work Directory

Output Spaces

--output-spaces is the option most worth understanding, because it decides what you actually get to analyze.

Data Sharing and Telemetry

Option What it does When to use it
--notrack Opt out of sending usage information to the fMRIPrep developers. Whenever your institution's data policy requires it.

Surface Reconstruction

fMRIPrep runs FreeSurfer's recon-all by default. It is by far the most expensive part of the pipeline.

Option What it does When to use it
--fs-no-reconall Skip FreeSurfer surface reconstruction entirely. Volume-based analyses that will never touch the surface. Substantially faster.
--fs-subjects-dir PATH Reuse an existing FreeSurfer subjects directory. You have already run recon-all yourself and do not want to pay for it twice.

This is a non-exhaustive list of tuning options. See the fMRIPrep usage documentation for the full set.

Further Reading