Execution and the BIDS format

The fmriprep workflow takes as principal input the path of the dataset that is to be processed. The only requirement to the input dataset is that it has a valid BIDS (Brain Imaging Data Structure) format. This can be easily checked online using the 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] [-v]
                [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [-s SESSION_ID] [-r RUN_ID] [-t TASK_ID] [--debug]
                [--nthreads NTHREADS] [--n_cpus NTHREADS]
                [--omp-nthreads OMP_NTHREADS] [--mem_mb MEM_MB]
                [--use-plugin USE_PLUGIN] [--anat-only]
                [--ignore {fieldmaps,slicetiming} [{fieldmaps,slicetiming} ...]]
                [--bold2t1w-dof {6,9,12}]
                [--output-space {T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} [{T1w,template,fsnative,fsaverage,fsaverage6,fsaverage5} ...]]
                [--template {MNI152NLin2009cAsym}]
                [--output-grid-reference OUTPUT_GRID_REFERENCE]
                [--skull-strip-ants] [--no-skull-strip-ants] [--fmap-bspline]
                [--fmap-no-demean] [--use-syn-sdc] [--force-syn]
                [--no-freesurfer] [--no-submm-recon] [-w WORK_DIR]
                [--reports-only] [--write-graph]
                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

-v, --version show program’s version number and exit

Options for filtering BIDS queries

 one or more participant identifiers (the sub- prefix can be removed)
-s, --session-id
 select a specific session to be processed
-r, --run-id select a specific run to be processed
-t, --task-id select a specific task to be processed

Options to handle performance

--debug run debug version of workflow
--nthreads maximum number of threads across all processes
--n_cpus total number of CPUs to use (alias for –nthreads)
--omp-nthreads maximum number of threads per-process
--mem_mb upper bound memory limit for FMRIPREP processes
--use-plugin nipype plugin configuration file
--anat-only run anatomical workflows only

Workflow configuration


Possible choices: fieldmaps, slicetiming

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


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

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.

Specific options for ANTs registrations

 use ANTs-based skull-stripping (default, slow))
 don’t use ANTs-based skull-stripping (use AFNI instead, fast)

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

 disable FreeSurfer preprocessing
 disable sub-millimeter (hires) reconstruction

Other options

-w, --work-dir path where intermediate results should be stored
--reports-only only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
--write-graph Write workflow graph.


Logs and crashfiles are outputted into the <output dir>/logs 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:

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.

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