There are two ways to install ASLPrep:
using Container Technologies (RECOMMENDED)
within a Manually Prepared Environment (Python 3.8+), also known as bare-metal installation
ASLPrep is not just a Python package; it also depends on a number of other neuroimaging libraries written in other languages. As such, in order to install ASLPrep you also need to install these other dependencies (with the right versions). Container software makes this straightforward, while the bare-metal approach is much more complicated and error-prone.
As such, we strongly recommend installing ASLPrep with Docker or Singularity.
ASLPrep is ideally run via a Docker or Singularity container. If you are running ASLPrep locally, we suggest Docker. However, for security reasons, many HPCs do not allow Docker containers, but do allow Singularity containers. The improved security for multi-tenant systems comes at the price of some limitations and extra steps necessary for execution.
ASLPrep’s image will take up ~30 GB of space on your machine. Please make sure to allocate Docker enough space to house the ASLPrep image before pulling it.
For every new version of ASLPrep that is released, a corresponding Docker image is generated and deployed to DockerHub.
In order to run ASLPrep via Docker, the Docker Engine must be installed.
If you have used ASLPrep via Docker in the past, you might need to pull down a more recent version of the image:
docker pull pennlinc/aslprep:<version>
The image can also be found here: https://registry.hub.docker.com/r/pennlinc/aslprep, and a full list of available tags (versions) can be found here: https://hub.docker.com/r/pennlinc/aslprep/tags.
In most cases, you will want to install the latest released version, which is the tag
Less frequently, you might want the latest unreleased version
(i.e., the version which corresponds to the
main branch on GitHub),
in which case you should use the tag
ASLPrep can be run interacting directly with the Docker Engine via the
docker run command,
or through a lightweight wrapper that was created for convenience.
Singularity version >= 2.5: If the version of Singularity installed on your HPC system is modern enough, you can create a Singularity image directly on the system using the following command:
singularity build aslprep-<version>.simg docker://pennlinc/aslprep:<version>
<version> should be replaced with the version of ASLPrep that you want to download.
Manually Prepared Environment (Python 3.8+)
This method is not recommended! Please use container alternatives described above instead.
ASLPrep requires some External Dependencies.
These tools must be installed and their binaries available in the system’s
On a functional Python 3.8 (or above) environment with
ASLPrep can be installed using the command:
pip install git+https://github.com/pennlinc/aslprep.git
Check your installation with the
ASLPrep is written using Python 3.8 (or above), is based on nipype, and requires some other neuroimaging software tools that are not handled by Python’s packaging system (PyPi) used to deploy the ASLPrep package:
If you would like to make changes to ASLPrep’s source code, but do not wish to directly contribute to the package, we recommend following the instructions in Contributing to ASLPrep.