Installation#

pyRadPlan requires Python 3.10 – 3.13. Earlier versions are not supported.

Setting up a virtual environment #

We strongly recommend working inside a dedicated virtual environment to avoid dependency conflicts with other projects.

venv (built-in)

python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Note

Name the environment .venv — all formatters and linters in pyRadPlan are pre-configured to ignore this folder automatically.

conda / mamba

conda create -n pyradplan python=3.12
conda activate pyradplan

Standard installation (PyPI)#

The simplest way to install pyRadPlan is from the Python Package Index:

pip install pyRadPlan

This pulls in all mandatory dependencies, including NumPy, SciPy, SimpleITK, pydantic, pydantic-ai, and everything else needed to run a full treatment planning workflow on the CPU with the NumPy backend.

Installation from source #

Clone the repository and install in editable mode so that any changes to the source are immediately reflected without reinstalling:

git clone https://github.com/e0404/pyRadPlan.git
cd pyRadPlan

# create and activate a virtual environment first (see above)
pip install -e .

The -e flag (editable) creates a link to the source tree rather than copying files into site-packages.

Optional extras #

pyRadPlan provides several pip extras for optional features. Install one or more by appending them in brackets, e.g. pip install pyRadPlan[dev,gui].

Extra	What it adds	When to use
`[dev]`	pytest, coverage, pytest-cov, pytest-benchmark, pre-commit, sphinx + extensions (numpydoc, pydata-sphinx-theme, sphinx-design, autodoc_pydantic, sphinx-autodoc-typehints)	Development, testing, and documentation builds
`[gui]`	PySide6 ≥ 6.0.1, pyqtgraph ≥ 0.12.0	Interactive Qt-based visualisation widgets
`[numba]`	numba ≥ 0.61.0	JIT-compiled acceleration of selected CPU code paths
`[matlab]`	matlabengine	Calling MATLAB / matRad directly from Python (see MATLAB and Octave interfaces)
`[octave]`	oct2py	Calling GNU Octave from Python (see MATLAB and Octave interfaces)

Example — full developer install from source:

pip install -e .[dev,gui]

GPU / alternate compute backends #

pyRadPlan’s numerical algorithms are written against the Python Array API standard. At runtime the library automatically detects which backends are available and selects the most capable one in this priority order:

CuPy (NVIDIA CUDA GPU) — highest priority when a GPU is present
PyTorch (NVIDIA CUDA GPU via torch.cuda)
JAX (CUDA GPU via JAX’s device list)
NumPy (CPU fallback — always available)

None of these GPU packages are installed automatically because they depend on the CUDA toolkit version on your machine. Follow the instructions below for whichever backend you want.

CuPy (recommended for GPU)#

CuPy provides a NumPy-compatible GPU array library. You must install the wheel that matches your CUDA toolkit version. Run nvcc --version or check nvidia-smi to find your CUDA version, then install the matching wheel:

# CUDA 12.x
pip install cupy-cuda12x

# CUDA 11.x
pip install cupy-cuda11x

See the CuPy installation guide for pre-built wheels for other CUDA versions and for conda-based installs.

PyTorch #

PyTorch can serve as both a CPU and GPU backend. The correct install command depends on your OS and CUDA version; use the selector on the PyTorch website to get the right command. A typical CUDA 12.x install looks like:

pip install torch --index-url https://download.pytorch.org/whl/cu124

For a CPU-only PyTorch backend:

pip install torch --index-url https://download.pytorch.org/whl/cpu

JAX #

JAX is auto-detected when present but is not an official optional extra. Install it manually following the JAX install guide.

Verifying backend detection #

After installing a GPU package, you can confirm that pyRadPlan sees it:

from pyRadPlan.core.xp_utils import (
    cupy_available, pytorch_gpu_available, jax_gpu_available,
    choose_array_api_namespace,
)
print("CuPy GPU:  ", cupy_available())
print("Torch GPU: ", pytorch_gpu_available())
print("JAX GPU:   ", jax_gpu_available())
print("Active ns: ", choose_array_api_namespace())

Development setup #

After installing with [dev], activate the pre-commit hooks so every commit is automatically formatted and linted:

pre-commit install

Verify the installation:

pre-commit --version
pytest test

The test suite targets Python 3.10–3.13. Run with coverage:

pytest --cov=pyRadPlan test

Building the documentation locally:

sphinx-build -b html docs docs/_build/html

MATLAB and Octave interfaces #

pyRadPlan can call into MATLAB or GNU Octave to run matRad algorithms directly. Both interfaces are optional.

MATLAB (`matlabengine`)#

The matlabengine package version must match your MATLAB release. Install the matching version manually before running pip install pyRadPlan[matlab] to avoid pip pulling an incompatible version:

# Example: MATLAB R2024a ships engine 24.1.*
pip install matlabengine==24.1.*
pip install pyRadPlan[matlab]   # skips matlabengine — already satisfied

See MATLAB Engine for Python for the exact version matrix.

GNU Octave (`oct2py`)#

pip install pyRadPlan[octave]

oct2py requires Octave to be installed on your system and accessible on the PATH.

Troubleshooting #

“No module named ‘pyRadPlan’” after editable install

Make sure your virtual environment is activated before running Python. Run pip show pyRadPlan to confirm the install target.

ImportError for SimpleITK on Apple Silicon

Use pip install SimpleITK --pre to get a pre-release wheel, or install via conda-forge: conda install -c conda-forge simpleitk.

CuPy import fails with CUDA driver error

The cupy-cudaXXx wheel must match the driver-supported CUDA version, not just the toolkit. Run nvidia-smi and compare “CUDA Version” with the wheel you installed.

PyTorch does not see the GPU

Confirm with python -c "import torch; print(torch.cuda.is_available())" and ensure the CUDA wheel matches your driver.

Pre-commit hook fails on first commit

The hook auto-fixes most style issues and then aborts the commit so you can review the changes. Stage the auto-fixed files and commit again:

git add -u
git commit -m "your message"