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. However, venv can be used by following the steps here.

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 (we recommended the latest available version). Here we call it nipoppy_env, but it can be named anything. In a Terminal window, run:

$ conda create --name nipoppy_env python=3

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:

$ python3 -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 python3 in the previous command)

Installing the nipoppy package

The latest release of Nipoppy can be installed from PyPI. In a Terminal window, run:

$ pip install nipoppy

Note

You can also install the “bleeding-edge” development version of Nipoppy from GitHub directly:

$ pip install git+https://github.com/nipoppy/nipoppy.git@main

This version is unstable, and things could break without any notice. Use at your own risk.

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 open 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 this 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.