Execution and the BIDS format

The sMRIPrep 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 sMRIPrep depends on the Installation method. The common parts of the command follow the BIDS-Apps definition. Example:

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

Command-Line Arguments

sMRIPrep: Structural MRI PREProcessing workflows

usage: smriprep
       [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
       [--bids-filter-file PATH]
       [--nprocs NPROCS]
       [--omp-nthreads OMP_NTHREADS]
       [--mem-gb MEM_GB]
       [--use-plugin USE_PLUGIN]
       [--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
       [--skull-strip-template SKULL_STRIP_TEMPLATE]
       [--skull-strip-mode {auto,skip,force}]
       [--fs-license-file PATH]
       [--fs-subjects-dir PATH]
       [-w WORK_DIR]
       [--run-uuid RUN_UUID]

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 sMRIPrep (see BIDS-Apps specification).

Named Arguments


show program’s version number and exit

Options for filtering BIDS queries

--participant-label, --participant_label

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


a JSON file describing custom BIDS input filters using pybids {<suffix>:{<entity>:<filter>,…},…} (

Options to handle performance

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

number of CPUs to be used.


maximum number of threads per-process

--mem-gb, --mem_gb

upper bound memory limit for sMRIPrep processes (in GB).


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


nipype plugin configuration file


generate boilerplate only

-v, --verbose

increases log verbosity for each occurence, debug level is -vvv

Workflow configuration


paths or keywords prescribing output spaces - standard spaces will be extracted for spatial normalization.


treat dataset as longitudinal - may increase runtime

Specific options for ANTs registrations


select a template for skull-stripping with antsBrainExtraction


do not use a random seed for skull-stripping - will ensure run-to-run replicability when used with –omp-nthreads 1


Possible choices: auto, skip, force

determiner for T1-weighted skull stripping (force ensures skull stripping, skip ignores skull stripping, and auto automatically ignores skull stripping if pre-stripped brains are detected).

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)

Surface preprocessing options


disable sub-millimeter (hires) reconstruction


disable FreeSurfer surface preprocessing.

Other options

-w, --work-dir

path where intermediate results should be stored


fast-track the workflow by searching for existing derivatives.


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


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


Specify UUID of previous run, to include error logs in report. No effect without –reports-only.


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 sMRIPrep developers. This information helps to improve sMRIPrep and provides an indicator of real world usage crucial for obtaining funding.


Use low-quality tools for speed - TESTING ONLY

The command-line interface of the docker wrapper

The sMRIPrep on Docker wrapper.

This is a lightweight Python wrapper to run sMRIPrep. Docker must be installed and running. This can be checked running

docker info

Please report any feedback to our GitHub repository ( and do not forget to credit all the authors of software that sMRIPrep uses (consider using the citation boilerplate included in the individual reports).

usage: smriprep-docker
       [-i IMG]
       [-w WORK_DIR]
       [--fs-license-file PATH]
       [--use-plugin PATH]
       [-f PATH]
       [-n PATH]
       [-p PATH]
       [--config PATH]
       [-e ENV_VAR value]
       [-u USER]

Positional Arguments


Possible choices: participant

Named Arguments

-h, --help

show this help message and exit


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


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


nipype plugin configuration file

Developer options

Tools for testing and debugging sMRIPrep

-f, --patch-smriprep

working smriprep repository

-n, --patch-niworkflows

working niworkflows repository

-p, --patch-nipype

working nipype repository


open shell in image instead of running sMRIPrep


Use custom nipype.cfg file

-e, --env

Set custom environment variable within container

-u, --user

Run container as a given user/uid


Run docker without TTY flag -it

The FreeSurfer license

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

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/smriprep:latest \
    /data /out/out \
    participant \
    --ignore fieldmaps

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

$ smriprep-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/smriprep:1.0.0 \
    /data /out participant

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

$ export FS_LICENSE=$HOME/.licenses/freesurfer/license.txt
$ smriprep-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/smriprep:1.0.0 \
    /data /out participant