Installation

Use QSIPrep as a container, with Docker or Apptainer. The Python package on PyPI is for people who maintain their own environment.

Once QSIPrep is installed, see Preparing your data for what it expects of the input and Running QSIPrep for the command line.

Docker Container

In order to run QSIPrep in a Docker container, Docker must be installed.

Note

If running Docker Desktop on MacOS (or via Docker Desktop), be sure to set the memory to 6 or more GB. Too little memory assigned to Docker Desktop can result in a message like Killed.

Mount the input, output and working directories into the container and give the container-side paths as arguments:

$ docker run -ti --rm \
    -v /path/to/bids:/data:ro \
    -v /path/to/output:/out \
    -v /path/to/work:/work \
    pennlinc/qsiprep:<version> \
    /data /out participant \
    -w /work --output-resolution 2

Replace <version> with a release tag. latest is the last release and unstable the current main branch; do not use unstable for anything but testing. No FreeSurfer license is needed.

To use the GPU, add --gpus all to docker run and --gpu with the tasks to accelerate to the QSIPrep options (see Head motion and eddy-current correction).

Apptainer Container

The easiest way to get an Apptainer (formerly Singularity) image is to run:

$ apptainer build qsiprep-<version>.sif docker://pennlinc/qsiprep:<version>

Where <version> should be replaced with the desired version of qsiprep that you want to download. Do not use latest or unstable unless you are performing limited testing.

Bind the input, output and working directories:

$ apptainer run --containall --writable-tmpfs \
    -B /path/to/bids,/path/to/output,/path/to/work \
    qsiprep-<version>.sif \
    /path/to/bids /path/to/output participant \
    -w /path/to/work --output-resolution 2

Add --nv to use the GPU.

Note

Running QSIPrep with Apptainer on Non-Internet Nodes

QSIPrep relies on TemplateFlow to provide standard anatomical templates. By default, it downloads necessary files into the $TEMPLATEFLOW_HOME directory (default: $HOME/.cache/templateflow). However, when running with --containall, the default location may not be accessible, and any missing templates will be tentatively downloaded into the temporary QSIPrep working directory instead. To avoid this, you must always set and bind TEMPLATEFLOW_HOME explicitly.

Steps to ensure successful execution:

1. On an internet-enabled node, set and bind the TEMPLATEFLOW_HOME variable to a persistent directory before running QSIPrep. This will ensure all necessary templates are downloaded into the specified location:

   export TEMPLATEFLOW_HOME=/path/to/persistent/templateflow
   apptainer run --cleanenv --containall \
     -B ${TEMPLATEFLOW_HOME}:${TEMPLATEFLOW_HOME} \
     --env "TEMPLATEFLOW_HOME=$TEMPLATEFLOW_HOME" \
     /path/to/qsiprep_<VERSION>.sif <your commands>
   

2. If the TEMPLATEFLOW_HOME directory is not accessible on your target HPC node, manually copy it to the target system after the first run.

3. On nodes without internet access, bind the copied TEMPLATEFLOW_HOME directory and set the environment variable as described above before running QSIPrep.

4. It may help to run a single subject or session on its own before running many jobs that access the templates. The single run will download the necessary templates and prevent multiple jobs from attempting to download the templates simultaneously.

For additional troubleshooting, see fmriprep docs or this thread on Neurostars.

Python Library

QSIPrep is on PyPI, but pip only installs the Python side:

$ pip install --user --upgrade qsiprep

Every tool listed under External Dependencies has to be installed and configured separately, so this route is for people who maintain their own environment and know why they want it. Everyone else should use a container.

External Dependencies

QSIPrep is written in Python 3.11 or later and is based on Nipype. The container image bundles the non-Python tools it calls. FSL, MRtrix3 (a release and the development branch), DSI Studio, AFNI, TORTOISE (including CUDA builds), FreeSurfer’s SynthStrip and SynthSeg, SynB0-DISCO, niimath and CUDA 12.2 come from the pennlinc/qsiprep-base image, whose versions are pinned in Dockerfile.base in the repository. ANTs and the Python environment are installed on top of it by Pixi in the main Dockerfile. Installing these tools yourself and running QSIPrep from PyPI is possible but not supported.