Execution and the BIDS format

The fmriprep workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T1w structural image and (unless disabled with a flag) a BOLD series. We highly recommend that you validate your dataset with the free, online BIDS Validator.

The exact command to run fmriprep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

fmriprep data/bids_root/ out/ participant -w work/

Command-Line Arguments

FMRIPREP: fMRI PREProcessing workflows

usage: fmriprep [-h] [--version]
                [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [-t TASK_ID] [--debug] [--nthreads NTHREADS]
                [--omp-nthreads OMP_NTHREADS] [--mem_mb MEM_MB] [--low-mem]
                [--use-plugin USE_PLUGIN] [--anat-only]
                [--ignore-aroma-denoising-errors] [-v]
                [--ignore {fieldmaps,slicetiming} [{fieldmaps,slicetiming} ...]]
                [--longitudinal] [--t2s-coreg] [--bold2t1w-dof {6,9,12}]
                [--output-space {T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} [{T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} ...]]
                [--force-bbr] [--force-no-bbr]
                [--template {MNI152NLin2009cAsym}]
                [--output-grid-reference OUTPUT_GRID_REFERENCE]
                [--medial-surface-nan MEDIAL_SURFACE_NAN] [--use-aroma]
                [--skull-strip-template {OASIS,NKI}] [--fmap-bspline]
                [--fmap-no-demean] [--use-syn-sdc] [--force-syn]
                [--fs-no-reconall] [--no-submm-recon] [--fs-license-file PATH]
                [-w WORK_DIR] [--resource-monitor] [--reports-only]
                [--run-uuid RUN_UUID] [--write-graph] [--stop-on-first-crash]
                bids_dir output_dir {participant}

Positional Arguments

bids_dir the root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).
output_dir the output path for the outcomes of preprocessing and visual reports

Possible choices: participant

processing stage to be run, only “participant” in the case of FMRIPREP (see BIDS-Apps specification).

Named Arguments

--version show program’s version number and exit

Options for filtering BIDS queries

--participant_label, --participant-label
 one or more participant identifiers (the sub- prefix can be removed)
-t, --task-id select a specific task to be processed

Options to handle performance

--debug run debug version of workflow
--nthreads, --n_cpus, -n-cpus
 maximum number of threads across all processes
--omp-nthreads maximum number of threads per-process
--mem_mb, --mem-mb
 upper bound memory limit for FMRIPREP processes
--low-mem attempt to reduce memory usage (will increase disk usage in working directory)
--use-plugin nipype plugin configuration file
--anat-only run anatomical workflows only
 ignores the errors ICA_AROMA returns when there are no components classified as either noise or signal
-v, --verbose increases log verbosity for each occurence, debug level is -vvv

Workflow configuration


Possible choices: fieldmaps, slicetiming

ignore selected aspects of the input dataset to disable corresponding parts of the workflow

--longitudinal treat dataset as longitudinal - may increase runtime
--t2s-coreg If provided with multi-echo BOLD dataset, create T2*-map and perform T2*-driven coregistration. When multi-echo data is provided and this option is not enabled, standard EPI-T1 coregistration is performed using the middle echo.

Possible choices: 6, 9, 12

Degrees of freedom when registering BOLD to T1w images. 9 (rotation, translation, and scaling) is used by default to compensate for field inhomogeneities.


Possible choices: T1w, template, fsnative, fsaverage, fsaverage6, fsaverage5

volume and surface spaces to resample functional series into
  • T1w: subject anatomical volume
  • template: normalization target specified by –template
  • fsnative: individual subject surface
  • fsaverage*: FreeSurfer average meshes
--force-bbr Always use boundary-based registration (no goodness-of-fit checks)
--force-no-bbr Do not use boundary-based registration (no goodness-of-fit checks)

Possible choices: MNI152NLin2009cAsym

volume template space (default: MNI152NLin2009cAsym)

 Grid reference image for resampling BOLD files to volume template space. It determines the field of view and resolution of the output images, but is not used in normalization.
 Replace medial wall values with NaNs on functional GIFTI files. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).

Specific options for running ICA_AROMA

--use-aroma add ICA_AROMA to your preprocessing stream

Specific options for ANTs registrations


Possible choices: OASIS, NKI

select ANTs skull-stripping template (default: OASIS))

Specific options for handling fieldmaps

--fmap-bspline fit a B-Spline field using least-squares (experimental)
 do not remove median (within mask) from fieldmap

Specific options for SyN distortion correction

--use-syn-sdc EXPERIMENTAL: Use fieldmap-free distortion correction
--force-syn EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available

Specific options for FreeSurfer preprocessing

--fs-no-reconall, --no-freesurfer
 disable FreeSurfer surface preprocessing. Note : –no-freesurfer is deprecated and will be removed in 1.2. Use –fs-no-reconall instead.
 disable sub-millimeter (hires) reconstruction
 Path to FreeSurfer license key file. Get it (for free) by registering at

Other options

-w, --work-dir path where intermediate results should be stored
 enable Nipype’s resource monitoring to keep track of memory and CPU usage
--reports-only only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
--run-uuid Specify UUID of previous run, to include error logs in report. No effect without –reports-only.
--write-graph Write workflow graph.
 Force stopping on first crash, even if a work directory was specified.

The docker wrapper CLI

fMRI Preprocessing workflow

usage: fmriprep-docker [-h] [--version] [-i IMG] [-w WORK_DIR]
                       [--output-grid-reference OUTPUT_GRID_REFERENCE]
                       [--fs-license-file PATH] [-f PATH] [-n PATH] [-p PATH]
                       [--shell] [--config PATH]
                       [bids_dir] [output_dir] [{participant}]

Positional Arguments

analysis_level Possible choices: participant

Named Arguments

-h, --help show this help message and exit
--version show program’s version number and exit
-i, --image image name

Wrapper options

Standard options that require mapping files into the container

-w, --work-dir path where intermediate results should be stored
 Grid reference image for resampling BOLD files to volume template space.
 Path to FreeSurfer license key file. Get it (for free) by registering at

Developer options

Tools for testing and debugging FMRIPREP

-f, --patch-fmriprep
 working fmriprep repository
-n, --patch-niworkflows
 working niworkflows repository
-p, --patch-nipype
 working nipype repository
--shell open shell in image instead of running FMRIPREP
--config Use custom nipype.cfg file


Logs and crashfiles are outputted into the <output dir>/fmriprep/sub-<participant_label>/log directory. Information on how to customize and understand these files can be found on the nipype debugging page.

Support and communication

The documentation of this project is found here:

All bugs, concerns and enhancement requests for this software can be submitted here:

If you have a problem or would like to ask a question about how to use fmriprep, please submit a question to with an fmriprep tag. is a platform similar to StackOverflow but dedicated to neuroinformatics.

All previous fmriprep questions are available here:

To participate in the fmriprep development-related discussions please use the following mailing list: Please add [fmriprep] to the subject line when posting on the mailing list.