Installation

parallelproj is a pure Python package for PET image reconstruction. It relies on two lower-level dependencies:

  • libparallelproj – a compiled C++/CUDA library providing the core projector implementations

  • parallelproj-core – a minimal Python interface to libparallelproj

Both libparallelproj and parallelproj-core are available on conda-forge and are documented at libparallelproj.readthedocs.io.

Note

We strongly recommend installing parallelproj from conda-forge, which automatically pulls in the correct pre-compiled libparallelproj variant (CPU or CUDA) for your system.

Requirements

  • Python ≥ 3.12.

  • A platform for which libparallelproj is built on conda-forge (Linux, macOS and Windows; CUDA builds are available on the platforms supported by the feedstock). conda-forge selects the right build automatically; you do not need to compile anything yourself.

Important

parallelproj cannot be installed with pip alone. Its compiled backend (libparallelproj / parallelproj-core) is distributed only through conda-forge, not on PyPI. Installing the pure-Python part with pip will import but fail at the first projection because the backend is missing. Always install from conda-forge as shown below.

Tip

You can get miniforge (a minimal conda installer configured for conda-forge) here. Alternatively, pixi is a modern, cross-platform package manager built on conda-forge that handles environments automatically. We recommend installing into a dedicated virtual environment regardless of the tool you choose.

Default install (auto CUDA detection)

The following commands create a new environment and install the package along with all required compiled libraries.

$ mamba create -n parallelproj -c conda-forge parallelproj

$ conda create -n parallelproj -c conda-forge parallelproj

Run the following from your project directory. pixi ties the environment to the directory rather than a global name.

$ pixi init -c conda-forge
$ pixi add parallelproj

After creation, activate the environment:

$ mamba activate parallelproj

$ conda activate parallelproj

$ pixi shell

Tip

To use parallelproj with PyTorch or CuPy, add them as extra dependencies:

$ mamba create -n parallelproj -c conda-forge parallelproj pytorch

$ mamba create -n parallelproj -c conda-forge parallelproj cupy

$ pixi add pytorch

$ pixi add cupy

Force a specific CUDA build

If you need a particular CUDA toolkit version of libparallelproj, you can pin it explicitly when creating the environment. Replace cuda129 below with the CUDA version matching your system (e.g. cuda129, cuda13).

$ mamba create -n parallelproj-cuda129 -c conda-forge cuda-version=12.9 parallelproj

$ conda create -n parallelproj-cuda129 -c conda-forge cuda-version=12.9 parallelproj

$ pixi add 'cuda-version=12.9' parallelproj

Force a CPU-only build

To explicitly install the CPU-only variant of libparallelproj (e.g. on a machine without a GPU):

$ mamba create -n parallelproj-cpu -c conda-forge parallelproj "libparallelproj=*=cpu*"

$ conda create -n parallelproj-cpu -c conda-forge parallelproj "libparallelproj=*=cpu*"

$ pixi add 'libparallelproj=*=cpu*' parallelproj

Verifying the installation

First check that the backend imports and report whether it was compiled with CUDA support:

import parallelproj
print(parallelproj.__version__)  # print version of parallelproj python package

import parallelproj_core
print(parallelproj_core.__version__)  # print version of compiled projector backend core library
print(parallelproj_core.cuda_enabled)  # 1 = CUDA enabled, 0 = CPU only

Then confirm that the full stack works end to end by building a small projector and running a forward and back projection (the same minimal example as the Quickstart).