Installation

Nipoppy is a Python package. We recommend installing it in a new or existing Python environment. The most common ways to create Python environments are through conda and venv.

Note

If you already have an existing Python environment setup, you can go directly to the Installing the nipoppy package section.

Supported operating systems

The Nipoppy tools are intended to be used on Linux operating system, and may not work on other operating systems. All processing pipelines with built-in support in Nipoppy are assumed to use Apptainer (formerly Singularity), which cannot run natively on Windows or macOS. Support for the Docker container platform may eventually be added, though that is not a priority at the moment.

Setting up a Python environment

Tip

If you do not already have Python set up on your system and/or wish to run Nipoppy locally, we recommend using conda instead of venv.

conda setup

Install conda (e.g. through Miniconda) following instructions from here.

Create a new environment (if needed) with Python version of at least 3.9. Here we call it nipoppy_env, but it can be named anything. In a Terminal window, run:

$ conda create --name nipoppy_env python=3.12

Tip

The conda cheatsheet is a useful reference for the most commonly used conda commands.

Activate the environment, e.g. by running:

$ conda activate nipoppy_env

venv setup

Note: These instructions assume you have an appropriate Python version installed.

Create the Python virtual environment in a directory of your choice. Here we call it nipoppy_env, but it can be named anything. In a Terminal window, run:

$ python -m venv nipoppy_env

Note

If you have multiple versions of Python installed, you should specify which one to use (e.g. python3.12 instead of python in the previous command)

On Compute Canada/Digital Research Alliance of Canada systems

If you are using one of the Compute Canada/Digital Research Alliance of Canada HPC systems, you should instead use virtualenv:

$ virtualenv --no-download nipoppy_env

See the Compute Canada wiki for more information.

Activate the virtual environment, e.g. by running:

$ source nipoppy_env/bin/activate

Installing the nipoppy package

From PyPI

We are actively working on publishing the package on PyPI, but for now it can only be installed by cloning the GitHub repository (see next section). Come back later for updates!

From GitHub

If you wish to use the latest (potentially unstable) version of the package, you can get it from the GitHub repository.

Clone the repository in a directory of your choice:

$ git clone https://github.com/nipoppy/nipoppy.git

Move into that directory and the nipoppy_cli subdirectory:

$ cd nipoppy/nipoppy_cli

Note

The nipoppy_cli subdirectory contains the newer version of the code, which has been refactored into a CLI. Eventually, it will become the only maintained version of the code. For the moment, the soon-to-be legacy code is still at the top level of the GitHub repository.

Install from the local source code in editable mode:

$ pip install -e .

Note

You can also install the package with dev dependencies (e.g., for running tests and building documentation):

$ pip install -e '.[dev]'

Verifying the install

Nipoppy was installed successfully if the CLI runs. The following command should print a usage message and exit without error:

$ nipoppy -h

Troubleshooting

Please create a GitHub issue for any error not covered below.

Error when installing pydantic-core

The latest version of the pydantic-core package (required by pydantic) is written in Rust, not pure Python. If package needs to be compiled during the install, but Rust is not available, then there might be an error complaining that Rust and/or Cargo cannot be found. In that case, if you are on an HPC system that uses lmod, try loading Rust before installing:

$ module load rust

Next steps

All done? See the Quickstart guide next for instructions on how to set up a Nipoppy dataset and configure pipelines.