Usage Notes


As of fMRIPrep 1.0.12, the software includes a tracking system to report usage statistics and errors. Users can opt-out using the --notrack command line argument.

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/

Further information about BIDS and BIDS-Apps can be found at the NiPreps portal.

Command-Line Arguments

fMRIPrep: fMRI PREProcessing workflows v23.1.3

usage: fmriprep [-h] [--skip_bids_validation]
                [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                [-t TASK_ID] [--echo-idx ECHO_IDX] [--bids-filter-file FILE]
                [--anat-derivatives PATH] [--bids-database-dir PATH]
                [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
                [--mem MEMORY_MB] [--low-mem] [--use-plugin FILE] [--sloppy]
                [--anat-only] [--boilerplate-only] [--reports-only]
                [--ignore {fieldmaps,slicetiming,sbref,t2w,flair} [{fieldmaps,slicetiming,sbref,t2w,flair} ...]]
                [--output-spaces [OUTPUT_SPACES ...]] [--longitudinal]
                [--bold2t1w-init {register,header}] [--bold2t1w-dof {6,9,12}]
                [--force-bbr] [--force-no-bbr]
                [--slice-time-ref SLICE_TIME_REF] [--dummy-scans DUMMY_SCANS]
                [--random-seed _RANDOM_SEED]
                [--me-t2s-fit-method {curvefit,loglin}]
                [--output-layout {bids,legacy}] [--me-output-echos]
                [--medial-surface-nan] [--project-goodvoxels]
                [--md-only-boilerplate] [--cifti-output [{91k,170k}]]
                [--aroma-melodic-dimensionality AROMA_MELODIC_DIM]
                [--error-on-aroma-warnings] [--return-all-components]
                [--fd-spike-threshold REGRESSORS_FD_TH]
                [--dvars-spike-threshold REGRESSORS_DVARS_TH]
                [--skull-strip-template SKULL_STRIP_TEMPLATE]
                [--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
                [--fmap-no-demean] [--use-syn-sdc [{warn,error}]]
                [--force-syn] [--fs-license-file FILE]
                [--fs-subjects-dir PATH] [--no-submm-recon] [--fs-no-reconall]
                [--track-carbon] [--country-code COUNTRY_CODE] [--version]
                [-v] [-w WORK_DIR] [--clean-workdir] [--resource-monitor]
                [--config-file FILE] [--write-graph] [--stop-on-first-crash]
                [--debug {compcor,fieldmaps,pdb,all} [{compcor,fieldmaps,pdb,all} ...]]
                bids_dir output_dir {participant}

Positional Arguments


The root folder of a BIDS valid dataset (sub-XXXXX folders should be found at the top level in this folder).


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).

Options for filtering BIDS queries

--skip_bids_validation, --skip-bids-validation

Assume the input dataset is BIDS compliant and skip the validation

--participant-label, --participant_label

A space delimited list of participant identifiers or a single identifier (the sub- prefix can be removed)

-t, --task-id

Select a specific task to be processed


Select a specific echo to be processed in a multiecho series


A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out


Reuse the anatomical derivatives from another fMRIPrep run or calculated with an alternative processing tool (NOT RECOMMENDED).


Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.

Options to handle performance

--nprocs, --nthreads, --n_cpus, --n-cpus

Maximum number of threads across all processes


Maximum number of threads per-process

--mem, --mem_mb, --mem-mb

Upper bound memory limit for fMRIPrep processes


Attempt to reduce memory usage (will increase disk usage in working directory)

--use-plugin, --nipype-plugin-file

Nipype plugin configuration file


Use low-quality tools for speed - TESTING ONLY

Options for performing only a subset of the workflow


Run anatomical workflows only

--boilerplate-only, --boilerplate_only

Generate boilerplate only


Only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.

Workflow configuration


Possible choices: fieldmaps, slicetiming, sbref, t2w, flair

Ignore selected aspects of the input dataset to disable corresponding parts of the workflow (a space delimited list)


Standard and non-standard spaces to resample anatomical and functional images to. Standard spaces may be specified by the form <SPACE>[:cohort-<label>][:res-<resolution>][...], where <SPACE> is a keyword designating a spatial reference, and may be followed by optional, colon-separated parameters. Non-standard spaces imply specific orientations and sampling grids. Important to note, the res-* modifier does not define the resolution used for the spatial normalization. To generate no BOLD outputs, use this option without specifying any spatial references. For further details, please check out


Treat dataset as longitudinal - may increase runtime


Possible choices: register, header

Either “register” (the default) to initialize volumes at center or “header” to use the header information when coregistering BOLD to T1w images.


Possible choices: 6, 9, 12

Degrees of freedom when registering BOLD to T1w images. 6 degrees (rotation and translation) are used by default.


Always use boundary-based registration (no goodness-of-fit checks)


Do not use boundary-based registration (no goodness-of-fit checks)


The time of the reference slice to correct BOLD values to, as a fraction acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end of acquisition. The alias start corresponds to 0, and middle to 0.5. The default value is 0.5.


Number of nonsteady-state volumes. Overrides automatic detection.


Initialize the random seed for the workflow


Possible choices: curvefit, loglin

The method by which to estimate T2* and S0 for multi-echo data. ‘curvefit’ uses nonlinear regression. It is more memory intensive, but also may be more accurate, than ‘loglin’. ‘loglin’ uses log-linear regression. It is faster and less memory intensive, but may be less accurate.


Exclude voxels whose timeseries have locally high coefficient of variation from surface resampling. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).

Options for modulating outputs


Possible choices: bids, legacy

Organization of outputs. “bids” (default) places fMRIPrep derivatives directly in the output directory, and defaults to placing FreeSurfer derivatives in <output-dir>/sourcedata/freesurfer. “legacy” creates derivative datasets as subdirectories of outputs.


Output individual echo time series with slice, motion and susceptibility correction. Useful for further Tedana processing post-fMRIPrep.


Replace medial wall values with NaNs on functional GIFTI files. Only performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).


Skip generation of HTML and LaTeX formatted citation with pandoc


Possible choices: 91k, 170k

Output preprocessed BOLD as a CIFTI dense timeseries. Optionally, the number of grayordinate can be specified (default is 91k, which equates to 2mm resolution)

[DEPRECATED] Options for running ICA_AROMA


Deprecated. Will raise an error in 24.0.


Deprecated. Will raise an error in 24.0.


Deprecated. Will raise an error in 24.0.

Options relating to confounds


Include all components estimated in CompCor decomposition in the confounds file instead of only the components sufficient to explain 50 percent of BOLD variance in each CompCor mask


Threshold for flagging a frame as an outlier on the basis of framewise displacement


Threshold for flagging a frame as an outlier on the basis of standardised DVARS

Specific options for ANTs registrations


Select a template for skull-stripping with antsBrainExtraction (OASIS30ANTs, by default)


Do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1 and matching –random-seed <int>


Possible choices: auto, skip, force

Perform T1-weighted skull stripping (‘force’ ensures skull stripping, ‘skip’ ignores skull stripping, and ‘auto’ applies brain extraction based on the outcome of a heuristic to check whether the brain is already masked).

Specific options for handling fieldmaps


Fit a B-Spline field using least-squares (experimental)


Do not remove median (within mask) from fieldmap

Specific options for SyN distortion correction


Possible choices: warn, error

Use fieldmap-less distortion correction based on anatomical image; if unable, error (default) or warn based on optional argument.


EXPERIMENTAL/TEMPORARY: Use SyN correction in addition to fieldmap correction, if available

Specific options for FreeSurfer preprocessing


Path to FreeSurfer license key file. Get it (for free) by registering at


Path to existing FreeSurfer subjects directory to reuse. (default: OUTPUT_DIR/freesurfer)


Disable sub-millimeter (hires) reconstruction


Disable FreeSurfer surface preprocessing.

Options for carbon usage tracking


Tracks power draws using CodeCarbon package


Country ISO code used by carbon trackers

Other options


show program’s version number and exit

-v, --verbose

Increases log verbosity for each occurrence, debug level is -vvv

-w, --work-dir

Path where intermediate results should be stored


Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of fMRIPrep.


Enable Nipype’s resource monitoring to keep track of memory and CPU usage


Use pre-generated configuration file. Values in file will be overridden by command-line arguments.


Write workflow graph.


Force stopping on first crash, even if a work directory was specified.


Opt-out of sending tracking information of this run to the FMRIPREP developers. This information helps to improve FMRIPREP and provides an indicator of real world usage crucial for obtaining funding.


Possible choices: compcor, fieldmaps, pdb, all

Debug mode(s) to enable. ‘all’ is alias for all available modes.

The command-line interface of the docker wrapper

Limitations and reasons not to use fMRIPrep

  1. Very narrow FoV images oftentimes do not contain enough information for standard image registration methods to work correctly. Also, problems may arise when extracting the brain from these data. fMRIPrep supports pre-aligned BOLD series, and accepting pre-computed derivatives such as brain masks is a target of future effort.

  2. fMRIPrep may also underperform for particular populations (e.g., infants) and non-human brains, although appropriate templates can be provided to overcome the issue.

  3. The “EPInorm” approach is currently not supported, although we plan to implement this feature (see #620).

  4. If you really want unlimited flexibility (which is obviously a double-edged sword).

  5. If you want students to suffer through implementing each step for didactic purposes, or to learn shell-scripting or Python along the way.

  6. If you are trying to reproduce some in-house lab pipeline.

(Reasons 4-6 were kindly provided by S. Nastase in his open review of our pre-print).

The FreeSurfer license

fMRIPRep uses FreeSurfer tools, which require a license to run.

To obtain a FreeSurfer license, simply register for free at

When using manually-prepared environments or singularity, FreeSurfer will search for a license key file first using the $FS_LICENSE environment variable and then in the default path to the license key file ($FREESURFER_HOME/license.txt). If using the --cleanenv flag and $FS_LICENSE is set, use --fs-license-file $FS_LICENSE to pass the license file location to fMRIPRep.

It is possible to run the docker container pointing the image to a local path where a valid license file is stored. For example, if the license is stored in the $HOME/.licenses/freesurfer/license.txt file on the host system:

$ docker run -ti --rm \
    -v $HOME/fullds005:/data:ro \
    -v $HOME/dockerout:/out \
    -v $HOME/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    nipreps/fmriprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps

Using FreeSurfer can also be enabled when using fmriprep-docker:

$ fmriprep-docker --fs-license-file $HOME/.licenses/freesurfer/license.txt \
    /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
    -v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    -v /path/to_output/dir:/out nipreps/fmriprep:1.0.0 \
    /data /out participant

If the environment variable $FS_LICENSE is set in the host system, then it will automatically used by fmriprep-docker. For instance, the following would be equivalent to the latest example:

$ export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt
$ fmriprep-docker /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
    -v /home/user/.licenses/freesurfer/license.txt:/opt/freesurfer/license.txt \
    -v /path/to_output/dir:/out nipreps/fmriprep:1.0.0 \
    /data /out participant

Reusing precomputed derivatives

Reusing a previous, partial execution of fMRIPrep

fMRIPrep will pick up where it left off a previous execution, so long as the work directory points to the same location, and this directory has not been changed/manipulated.

Using a previous run of FreeSurfer

fMRIPrep will automatically reuse previous runs of FreeSurfer if a subject directory named freesurfer/ is found in the output directory (<output_dir>/freesurfer). Reconstructions for each participant will be checked for completeness, and any missing components will be recomputed. You can use the --fs-subjects-dir flag to specify a different location to save FreeSurfer outputs. If precomputed results are found, they will be reused.

The anatomical fast-track

Starting with version 20.1.0, fMRIPrep has a command-line argument (--anat-derivatives <PATH>) to indicate a path from which the preprocessed information derived from the T1w, T2w (if present) and FLAIR (if present) images. This feature was envisioned to help process very large multi-session datasets where the anatomical images can be averaged (i.e., anatomy is not expected to vary substantially across sessions). An example where this kind of processing would be useful is My Connectome, a dataset that contains 107 sessions for a single-subject. Most of these sessions contain anatomical information which, given the design of the dataset, can be averaged across sessions as no substantial changes should happen. In other words, the anatomical information of the dataset can be considered as cross-sectional. Before version 20.1.0, preprocessing this dataset would be hard for two limitations:

  • if the dataset were to be processed in just one enormous job (be it in a commercial Cloud or HPC resources), the amount of data to be processed surely would exceed the time limitations per job (and/or related issues, such as restarting from where it left before); or

  • if the processing were split in sessions, then fMRIPrep would attempt to re-process the anatomical information for every session.

Because processing this emerging type of datasets (densely sampled neuroimaging) was impractical with fMRIPrep, the option --anat-derivatives will shortcut the whole anatomical processing.


Using the anatomical fast-track (the --anat-derivatives argument) has important side-effects that risk the reproducibility and reliability of fMRIPrep. This flag breaks fMRIPrep’s internal tracing of provenance, and it trusts whatever input fMRIPrep is given (so long it is BIDS-Derivatives compliant and contains all the necessary files).

When reporting results obtained with --anat-derivatives, please make sure you highlight this particular deviation from fMRIPrep, and clearly describe the alternative preprocessing of anatomical data.


When the intention is to combine the anatomical fast-track with some advanced options that involve standard spaces (e.g., --cifti-output), please make sure you include the MNI152NLin6Asym space to the --output-spaces list in the first invocation of fMRIPrep (or sMRIPrep) from which the results are to be reused. Otherwise, a warning message indicating that fMRIPrep’s expectations were not met will be issued, and the pre-computed anatomical derivatives will not be reused.


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.

Previous questions about fMRIPRep 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.

About the NiPreps framework licensing

Please check for detailed information on the criteria we use to license fMRIPrep and other projects of the framework.

License information

Copyright (c) 2023, the NiPreps Developers.

As of the 21.0.x pre-release and release series, fMRIPrep is licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright (c) 2015-2023, the fMRIPrep developers and the CRN. All rights reserved.

fMRIPrep 20.2 series and earlier are licensed under the BSD 3-clause license. You may obtain a copy of the License at

All trademarks referenced herein are property of their respective holders.

The fmriprep-wrapper for Docker

Copyright (c) 2020-2023, the NiPreps Developers. Copyright (c) 2015-2020, the fMRIPrep developers and the CRN. All rights reserved.

fMRIPrep-wrapper is licensed under the BSD 3-clause license. You may obtain a copy of the License at

All trademarks referenced herein are property of their respective holders.